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The  object  oriented  programming  style  used  in  the  Smalltalk  and  Actor  languages  is  available  in 
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operations  on  objects.  Fart  of  its  implementation  is  simply  a  convention  in  procedure  calling 
style:  part  is  a  powerful  language  feature,  called  Flavors,  for  defining  abstract  objects.  Tin- 
chapter  attempts  to  explain  what  programming  with  objects  snd  with  message  passing  mean-,  tlio 
various  means  of  implementing  these  in  Lisp  Machine  Lisp,  and  when  you  should  use  them.  It 
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Preface 


This  memo  is  intended  to  become  a  chapter  in  the  Lisp  Machine  manual  the  next  time  it  is 
published.  Since  there  is  a  pressing  need  for  documentation  on  flavors,  we  are  publishing  it 
immediately  as  a  memo.  The  authors  therefore  assume  that  the  reader  has  encountered  this  t«>t 
while  reading  the  manual.  We  assume  that  the  reader  is  familiar  with  the  basics  of  Lisp  and  the 
Lisp  Machine's  dialect  in  particular:  we  also  make  particular  references  to  an  example  ft  * -m 
section  17.1  in  the  manual. 

Any  comments,  suggestions,  or  criticisms  will  be  welcomed.  The  authors  can  be  reached  by 
any  of  the  following  communication  paths: 

ARPA  Network  mail  to  BUG-LMMANQMIT-Al 

U.S.  Mail  to 

Daniel  L.  Weinreb  or  David  A.  Moon 
545  Technology  Square 
Cambridge,  Mass.  02139 


Note 

This  document  was  edited  with  the  Zmacs  and  Emacs  editors,  and  formated  by  the  Bolio  test 
justifier.  It  was  printed  on  the  MIT’s  Dover  Printer, 
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Objects.  Message  Passing.  anil  Flavors 


I.  Objects,  Message  Passing,  and  Flavors 

l.l  Introduction 

The  object  oriental  programming  st>  lo  used  in  the  Smalltalk  ami  Actoi  l.nmlics  of  languages 
is  available  in  l  isp  Machine  I  isp.  anil  used  by  the  I  isp  Machine  software  svstem.  It  is  used  to 
perform  generic  operations  on  objects.  Part  of  its  implementation  is  simply  a  convention  in 
procedure  calling  style;  part  is  a  pov  *ul  language  feature,  called  Havors.  tor  defining  abstract 
objects.  This  chapter  attempts  to  explain  what  programming  with  rbjetls  and  with  message 
passing  means,  the  various  means  of  implementing  these  in  I  isp  Mac. tine  I  isp  and  when  you 
should  use  them.  It  assumes  no  prior  knowledge  of  any  other  languages. 


1.2  Objects 

When  writing  a  program,  it  is  often  convenient  to  model  what  the  program  does  in  terms  of 
objects:  conceptual  entities  that  can  be  likened  to  real-world  things.  Choosing  what  objects  to 
provide  in  a  program  is  very  important  to  the  proper  organization  of  the  program.  In  an  object- 
oriented  design,  specifying  what  objects  exist  is  the  first  task  in  designing  the  system.  In  a  text 

editor,  the  objects  might  be  "pieces  of  text",  "pointers  into  text",  and  "display  windows".  In  an 

electrical  design  system,  the  objects  might  he  "resistors”,  "capacitors",  "transistors",  "wires",  and 
"display  windows".  After  specifying  what  objects  there  arc,  the  next  task  of  die  design  is  to 
figure  out  what  operations  can  be  performed  on  each  object.  In  the  text  editor  example, 
operations  on  "pieces  of  text"  might  include  inserting  text  and  deleting  text;  operations  on 
"pointers  into  text"  might  include  moving  forward  and  backward;  and  operations  on  "display 
windows"  might  include  redisplaying  die  window  and  changing  with  which  "piece  of  text"  the 
window  is  associated. 

In  this  model,  wc  think  of  the  program  as  being  built  around  a  set  of  objects,  each  of  which 
has  a  set  of  operations  that  can  be  performed  on  it.  More  rigorously,  the  program  defines  several 
types  of  object  (the  editor  above  has  three  types),  and  it  can  create  many  instances  of  each  type 
(that  is,  there  can  he  many  pieces  of  text,  many  pointers  into  text,  and  many  windows).  Che 
program  defines  a  set  of  types  of  object,  and  the  operations  that  can  be  performed  on  any  of  the 
instances  of  each  type. 

I'his  should  not  be  wholly  unfamiliar  to  the  reader,  Harlicr  in  diis  manual,  wc  saw  a  few 
examples  of  this  kind  of  programming.  A  simple  example  is  disembodied  property  lists,  and  the 
functions  get.  putprop.  and  remprop.  I  lie  disembodied  property  list  is  a  type  of  object:  you 

can  instantiate  one  with  (cons  nil  nil)  (that  is.  by  evaluating  tins  form  you  can  create  a  new 

disembodied  property  list):  thcie  arc  tluce  operations  on  the  object,  namely  gel.  putprop.  and 
remprop.  Another  example  in  the  manual  was  the  first  example  of  the  use  ot  defstruct.  which 
was  called  a  ship,  defstruct  automatically  defined  some  operations  on  this  object:  the  operations 
lo  access  its  elements.  Wc  could  define  other  functions  that  did  useful  things  with  ships,  such  as 
computing  their  speed,  angle  of  travel,  momentum,  or  velocity,  slopping  them,  moving  them 
elsewhere,  and  so  on. 
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In  both  cases,  we  repiescnt  our  conccpm.il  object  by  one  l.isp  object.  I  he  I  isp  object  we  use 
for  the  representation  Inis  Mrueture.  anil  refers  to  other  I  isp  objects.  In  the  property  list  case, 
the  l.isp  object  is  a  list  with  alternating  indicators  and  values;  in  the  ship  ease,  the  I  isp  object  is 
an  array  whose  details  are  taken  care  of  by  delstruct  In  both  cases,  we  can  say  that  the  object 
keeps  trick  of  an  internal  stale  which  can  be  eMwunetl  and  iiltiieJ  by  the  operations  available 
for  that  type  of  object,  get  examines  the  state  of  a  propeity  list,  and  putprop  alters  it:  ship  x 
position  and  ship -get -momentum  examine  the  state  of  a  ship,  and  (setf  (ship  mass)  5  0)  and 
(ship -move  to  3.0  4.0)  alter  it. 

We  have  now  seen  the  essence  of  object-oriented  programming.  A  conceptual  object  is 
modelled  by  a  single  I  isp  object,  which  bundles  up  some  stale  information,  for  every  type  of 
object,  there  is  a  set  of  operations  dial  can  be  performed  to  examine  or  alter  the  state  of  the 
object. 

1.3  Modularity 

An  important  benefit  of  the  object-oriented  style  is  that  it  lends  itself  to  a  panieulatly  simple 
and  lucid  kind  of  modularity,  if  you  have  modular  programming  constructs  and  techniques 
availabile,  it  helps  and  encourages  you  to  write  programs  that  are  easy  to  read  and  understand, 
and  so  are  more  reliable  and  maintainable.  Object-oriented  programming  lets  a  programmer 
implement  a  useful  facility  that  presents  the  caller  with  a  set  of  external  interfaces,  without 
requiring  the  caller  to  understand  how  the  internal  details  of  the  implementation  work.  In  other 
words,  a  program  that  calls  this  facility  can  treat  the  facility  as  a  black  box;  the  program  knows 
what  the  facility's  external  interfaces  guarantee  to  do.  and  that  is  all  it  knows. 

For  example,  a  program  that  uses  disembodied  property  lists  iv,..  needs  to  know  that  the 
property  list  is  being  maintained  as  a  list  of  alternating  indicators  and  values;  the  program  simply 
performs  the  operations,  passing  them  inputs  and  getting  hack  outputs.  The  piogram  only 
depends  on  the  external  definition  of  these  operations:  it  knows  that  il  it  putprops  a  pioperty, 
and  doesn't  remprop  it  (or  putprop  over  it),  then  it  can  do  get  and  he  sure  of  getting  hack  the 
same  thing  it  put  in.  I  he  important  thing  about  this  hiding  of  the  details  of  the  implementation 
is  that  someone  reading  a  program  that  uses  disembodied  property  lists  need  not  concern  himself 
with  how  they  .ac  implemented;  lie  need  only  understand  wli.u  they  undertake  to  do  lliis  saves 
die  programmer  a  lot  of  tunc,  and  lets  him  concentrate  his  energies  on  understanding  the 
program  he  is  working  on.  Another  good  thing  about  this  biding  is  that  the  icpresenlation  of 
property  lists  could  be  changed,  and  the  progi.tni  would  continue  u>  work,  l-ot  example,  instead 
of  a  list  of  alternating  elements,  the  property  list  could  he  implemented  as  an  association  list  or  a 
hash  table.  Nothing  in  the  calling  program  would  change  at  all. 

The  same  is  true  of  the  ship  example  The  caller  is  presented  wuh  a  collection  of  opemlions. 
such  as  ship  x  position,  ship  y  position,  ship  spoor  I.  and  slop  direction;  il  -amply  calls 
these  and  looks  at  then  answers,  without  caring  how  tliev  did  wh.il  lliev  did.  In  our  example 
above,  slop  x  position  and  ship-y  position  would  he  aaessor  functions,  defined  automatically 
by  defstruct.  while  ship -speed  and  ship  direction  would  he  functions  defined  In  the 
implementor  ol  the  ship  type  Ihe  code  might  look  like  this: 


I  >Sk  1  MM  \  VI  1  AYOR  55 


If.  I  \\  SI 


flavors 


3 


Modularity 


(defstruct  (ship) 
sh ip-x-pos i t ion 
ship  -y-pos i ti on 
ship-x-velocity 
ship-y  veloci ty 
sh ip-mass ) 

(defun  ship-speed  (ship) 

(sqrt  (+  (*  ( sh i p-x- ve loci ty  ship)  2) 

(~  ( ship-y-veloci ty  ship)  2)))) 

(defun  ship-direct  .on  (ship) 

(atan  ( shi p-y- vel oc i ty  ship) 

(ship-x-velocity  ship))) 

The  caller  need  not  know  that  the  first  two  functions  were  structure  accessors  and  that  the 
second  two  were  written  by  hand  and  do  arithmetic.  Those  Tacts  would  not  be  considered  part  of 
the  black  box  characteristics  of  the  implementation  of  the  ship  type.  The  ship  type  docs  not 
guarantee  which  functions  will  be  implemented  in  which  ways;  such  aspects  arc  not  part  of  the 
contract  between  ship  and  its  callers.  In  fact,  ship  could  have  been  written  this  way  instead: 

(defstruct  (ship) 
ship-x-posi tion 
ship-y-position 
siiip-speed 
ship-direction 
ship-mass) 

(defun  ship-x-velocity  (ship) 

(*  (ship-speed  ship)  (cos  (ship-direction  ship)))) 

(defun  ship-y-velocity  (ship) 

(*  (ship-speed  ship)  (sin  (ship-direction  ship)))) 

In  this  second  implementation  of  the  ship  type,  we  have  decided  to  store  the  velocity  in  polar 
coordinates  instead  of  rectangular  coordinates.  This  is  purely  an  implementation  decision;  the 
caller  has  no  idea  which  of  the  two  ways  the  implementation  works,  because  he  just  performs  the 
operations  on  the  object  by  calling  the  appropriate  functions. 

We  have  now  created  our  own  types  of  objects,  whose  implementations  are  hidden  from  the 
programs  that  use  them.  Such  types  arc  usually  referred  to  as  abstract  types.  The  object-oriented 
style  of  programming  can  be  used  hi  create  abstract  types  by  hiding  the  implementation  of  the 
operations,  and  simply  documenting  what  the  operations  arc  defined  to  do. 

Some  more  terminology:  the  quantities  being  held  by  die  elements  of  the  ship  slructurc  are 
referred  to  as  instance  variables,  liacli  instance  of  a  type  has  the  same  operations  defined  on  it; 
what  distinguishes  one  instance  from  another  (besides  identity  (eqncss))  is  die  values  that  reside  in 
its  instance  variables.  I  lie  example  above  illustrates  dial  a  caller  of  operations  docs  not  know 
what  the  instance  variables  are;  our  two  ways  of  writing  die  ship  operations  have  different 
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instance  variables,  but  from  the  outside  they  have  exactly  the  sarnie  operations. 

One  might  ask:  "lint  what  if  the  caller  evaluates  (aref  ship  3)  and  notices  that  he  gets  hack 
the  x-velocily  rather  than  the  speed?  Then  he  can  tell  which  of  the  two  implementations  were 
used."  I  his  is  true;  if  the  caller  were  to  do  that,  he  could  tell.  However,  when  a  lacilily  is 
implemented  in  the  object-oriented  style,  only  certain  functions  are  documented  and  advertised: 
the  functions  which  are  considered  to  be  operations  on  the  type  of  object.  I  he  contrail  from 
ship  to  its  callers  only  speaks  about  what  happens  if  the  caller  calls  these  functions.  I  he  contract 
makes  no  guarantees  at  all  about  what  would  happen  if  the  caller  were  to  start  poking  around  on 

his  own  usitie  aref.  A  caller  who  docs  so  is  in  error,  he  is  depending  on  something  that  is  not 

specified  it  ie  contract.  No  guarantees  were  ever  made  about  the  resu-ts  of  such  action,  and  so 
anything  may  happen:  indeed,  ship  may  get  reimplemented  overnight,  and  the  code  that  does  the 
aref  will  have  a  dilVercni  effect  entirely  and  probably  stop  working.  Ilus  example  shows  why  the 
concept  of  a  contract  between  a  calico  and  a  caller  is  important:  the  contract  is  what  spa  dies  the 
interface  between  the  two  modules. 

Unlike  some  other  languages  that  provide  abstract  types.  I  isp  Machine  I  isp  makes  no  attempt 

to  have  the  language  automatically  forbid  constructs  that  circumvent  the  contract.  Ibis  is 

intentional.  One  reason  for  this  is  that  die  I  isp  Machine  is  an  interactive  system,  and  so  it  is 
important  to  be  able  to  examine  and  alter  internal  state  interactively  (usually  from  a  debugger). 
Furthermore,  there  is  no  strong  distinction  between  the  "system"  programs  and  the  "user" 
programs  on  the  l  isp  Machine;  users  are  allowed  to  get  into  any  pari  of  die  language  system  and 
change  what  they  want  to  change. 

In  summary:  by  defining  a  set  of  operations,  and  making  only  a  sp-’ilic  set  of  external 
entry  points  available  to  the  caller,  the  programmer  can  cieate  his  own  abstract  types.  These  types 
can  be  useful  facilities  for  other  programs  and  programmers.  Since  me  implementation  of  the 
type  is  hidden  from  the  callers,  modularity  is  maintained,  and  the  implementation  can  be  changed 
easily. 

We  have  hidden  die  implementation  of  an  abstract  type  by  making  its  operations  into 
functions  which  the  user  may  call.  The  important  thing  is  not  that  they  ate  functions  m  I  isp 
everything  is  done  with  functions.  The  important  thing  is  that  we  have  defined  a  new  conceptual 
operation  and  gi'  ei.  it  a  name,  rather  than  requiring  anyone  who  wants  to  do  the  opei.ition  to 
write  it  out  step-by-step.  Thus  we  say  (ship-x  velocity  s)  rather  than  (aref  s  2). 

It  is  just  as  true  of  such  abstract-operation  functions  as  of  ordinary  functions  that  sometimes 
they  arc  simple  enough  that  we  want  the  compiler  to  compile  special  code  for  them  rather  than 
really  calling  the  function.  (Compiling  special  code  like  this  is  often  called  open  -iodine,  )  I  lie 
compiler  is  directed  to  do  this  through  use  of  macros,  dcfsiibsis.  or  optimizers,  dofstiuct 
arranges  for  this  kind  of  special  compilation  for  the  functions  that  get  the  instance  variables  of  a 
structure. 

When  we  use  this  optimization,  the  implementation  of  the  abstract  tv pe  is  only  hidden  m  a 
certain  sense.  It  does  not  appear  in  the  I  isp  code  written  by  the  user,  hut  does  appeal  in  the 
compiled  code.  I  he  reason  is  that  there  may  be  some  compiled  functions  that  use  the  nimios  (or 
whatever);  even  if  you  change  the  definition  of  the  macro,  the  existing  compiled  code  will 
continue  to  use  the  old  definition.  I  bus,  if  the  implementation  of  a  module  is  changed  piogiains 
that  use  it  may  need  to  be  recompiled.  This  is  something  we  sometimes  accept  for  the  sake  of 
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efficiency. 

In  the  present  implcmcntatu  n  of  flavors,  which  is  discussed  below,  there  is  no  such  compiler 
incorporation  of  nonmodular  knowledge  into  a  program,  except  when  the  "outside-accessible 
instance  variables"  feature  is  used,  see  page  22.  where  this  problem  is  explained  further.  It'  you 
don't  use  the  "outside-accessible  instance  xaiiuMcs"  feature,  you  don't  luxe  to  worn  about  tins. 


1.4  Generic  Operations 

Suppose  we  think  about  the  rest  of  the  program  that  uses  the  ship  abstraction.  It  may  want 
to  deal  with  other  objects  that  are  like  ships  in  that  they  are  movable  objects  with  mass,  but 
unlike  ships  in  other  ways.  A  more  advanced  model  of  a  ship  might  include  the  concept  of  tire 
ship's  engine  power,  the  nutnbet  of  passengers  on  board,  and  its  name.  An  object  representing  a 
meteor  probably  would  not  have  any  of  these,  but  might  have  another  attribute  such  as  how 
much  iron  is  in  it. 

However,  all  kinds  of  movable  objects  have  positions,  velocities,  and  masses,  and  the  system 
will  contain  some  programs  that  deal  with  these  quantities  in  a  uniform  wax.  regardless  of  what 
kind  of  object  the  attributes  apply  to.  For  example,  a  piece  of  the  system  that  calculates  every 
object's  orbit  in  space  need  not  worry  about  the  other,  more  peripheral  attributes  of  various  types 
of  objects;  it  works  the  same  way  for  all  objects.  Unfortunately,  a  program  that  tries  to  calculate 
the  orbit  of  a  ship  will  need  to  know  the  ship's  attributes,  and  will  have  to  call  ship-x-position 
and  ship-y-velocity  and  so  on.  The  problem  is  that  these  functions  won't  work  for  meteors. 
There  would  have  to  be  a  second  program  to  calculate  orbits  for  meteors  that  would  be  exactly 
the  same,  except  that  where  the  first  one  calls  ship-x-position.  the  second  one  would  call 
meteor-x-position,  and  so  on.  T  his  would  be  very  bad;  a  great  deal  of  code  would  have  to 

exist  in  multiple  copies,  all  of  it  would  have  to  be  maintained  in  paullcl,  and  it  would  take  up 

space  for  no  good  reason. 

What  is  needed  is  an  operation  that  can  be  performed  on  objects  of  several  different  types. 
For  each  type,  it  should  do  the  thing  appropriate  for  that  type.  Such  operations  arc  called 
generic  operations,  flic  classic  example  of  generic  operations  is  the  arithmetic  functions  in  most 
programming  languages,  including  f.isp  Machine  l  isp.  The  +  (or  plus)  function  will  accept 
either  ftxnums  or  donums,  and  perform  either  fixntun  addition  or  llomim  addition,  whichever  is 
appropriate,  based  on  the  data  types  of  the  objects  being  manipulated.  In  our  example,  we  need 
a  generic  x- position  operation  Unit  can  be  performed  on  either  ships,  meteors,  or  any  other 
kind  of  mobile  object  represented  in  the  system.  This  way.  we  can  write  a  single  program  to 
calculate  orbits.  When  it  wants  to  know  the  v  position  of  the  object  n  is  dealing  with,  it  simply 
invokes  the  generic  x-position  operation  on  the  object,  and  whatever  type  of  object  it  has,  the 
correct  operation  is  performed,  and  the  \  position  is  returned. 

A  terminology  for  the  use  of  such  generic  operations  has  emerged  from  the  Smalltalk  and 
Actor  languages:  performing  a  generic  operation  is  called  semling  a  message.  The  objects  in  the 
program  arc  thought  of  as  little  people,  who  get  sent  messages  and  respond  with  answers.  In  the 

example  above,  the  objects  arc  sent  x  position  messages,  to  which  they  respond  with  their  x 

position.  This  message  passing  is  how  generic  operations  arc  performed. 
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Sending  a  message  is  a  way  of  invoking  a  function.  Along  with  the  mime  of  the  message,  in 
general,  some  arguments  are  passed:  when  the  object  is  done  with  the  message,  some  values  are 
returned.  I  he  sender  of  the  message  is  simply  calling  a  function  w  ill  some  arguments,  and 
getting  some  values  back.  The  interesting  thing  is  that  the  caller  did  not  specify  the  name  of  a 
procedure  to  call.  Instead,  it  specified  a  message  name  and  .in  object:  that  is.  it  said  what 
operation  to  perform,  and  what  object  to  perform  it  on.  The  function  to  invoke  was  found  from 
this  information. 

When  a  message  is  sent  to  an  object,  a  function  therefore  must  be  found  to  handle  the 
message.  The  two  data  used  to  figure  out  which  function  to  call  are  the  type  of  the  object,  and 
the  minie  of  the  message.  The  same  set  of  functions  are  used  for  all  instances  of  a  given  type,  so 
the  type  is  the  only  attribute  of  die  object  used  to  figure  out  which  function  to  call.  I  he  rest  of 
the  message  besides  the  name  arc  data  which  arc  passed  as  argument  to  die  function,  so  the 
name  is  the  only  part  of  the  message  used  to  find  the  function.  Su.ii  .1  function  is  called  a 
method.  Tor  example,  if  we  send  an  x- position  message  to  an  object  of  type  ship,  then  the 
function  wc  find  is  "the  ship  type’s  x- position  method".  A  method  is  a  function  that  handles  a 
specific  kind  of  message  to  a  specific  kind  of  object:  this  method  handles  messages  named  x- 
position  to  objects  of  type  ship. 

In  our  new  terminology:  the  orbit  calculating  program  finds  the  x  position  of  the  object  it  is 
working  on  by  sending  that  object  a  message  named  x-position  (with  no  arguments),  flic 
returned  value  of  die  message  is  die  x  position  of  the  object.  If  die  object  was  of  type  ship, 
then  the  ship  type's  x-position  method  was  invoked:  if  it  was  of  type  meteor,  then  die  meteor 
type's  x-position  method  was  invoked.  The  orbit-calculating  program  just  sends  the  message,  and 
the  right  Function  is  invoked  based  on  die  type  of  die  object.  Wc  now  have  true  generic 
functions,  in  the  form  of  message  passing:  the  same  operation  can  mean  different  tilings 
depending  on  die  type  of  the  object. 

1.5  Generic  Operations  in  Lisp 

How  do  we  implement  message  passing  in  I  .isp?  By  convention,  objects  that  receive  messages 
are  always  Junctional  objects  (that  is,  you  can  apply  them  to  arguments),  and  a  message  is  m;m  to 
an  object  by  calling  that  object  as  a  function,  passing  the  name  of  the  message  as  the  first 
argument,  and  the  arguments  of  the  message  as  the  rest  of  die  arguments.  Message  names  ate 
represented  by  symbols:  normally  these  symbols  arc  in  the  keyword  package  (see  chapter  19  of 
the  l  isp  Machine  Manual)  since  messages  are  a  protocol  for  communication  between  diffeienl 
programs,  which  may  reside  in  different  packages.  So  if  wc  have  a  variable  my  ship  whose  value 
is  an  object  of  type  ship,  and  wc  want  to  know  its  ,v  position,  we  send  it  a  message  as  follows: 

(funcall  my-ship  ’ : x-posi t i on  ) 

litis  form  returns  die  x  position  as  its  returned  value.  To  set  the  ship's  v  position  to  AO.  we 
send  it  a  message  like  litis: 

(funcall  my-ship  ' : set-x-posi t  ion  3.0) 

It  should  be  stressed  that  no  new  features  are  added  to  I  isp  for  message  sending:  we  simply 
define  a  convention  on  the  way  objects  lake  arguments.  I  lie  convention  says  dial  an  ohjevt 
accepts  messages  by  always  interpreting  its  first  argument  as  a  message  name  I  lie  objeU  must 
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consider  iliis  message  name,  lind  [lie  function  which  is  ihe  meihnd  fur  dial  message  name,  ami 
invoke  that  function. 

I  his  raises  the  question  of  how  message  receiving  works.  The  object  must  somehow  timl  the 
right  method  for  the  message  it  is  sent.  I  urtliermoie.  the  object  now  has  to  he  .  .illahl-'  as  a 
function:  objects  can  t  just  be  cfefstructs  any  more,  ‘.nee  those  aren't  functions,  lint  (he  structure’ 
defined  in  defstruct  was  doing  something  useful;  it  was  holding  the  instance  , ariables  (die 
internal  state)  ol  the  object.  We  need  a  function  with  internal  state:  that  is.  we  need  a  coroutine. 

Of  the  l  isp  Machine  1  isp  features  presented  so  far,  the  most  appi  ipriate  is  the  closure  (see 
chapter  10  ot  the  1  isp  Machine  Manual).  A  message-receiving  object  cold  be  implemented  as  a 
closure  over  a  set  ol  instance  variables.  Ihe  function  inside  the  closure  would  have  a  big  selectq 
form  to  dispatch  on  its  fust  argument.  (Actually,  rather  than  using  closures  and  a  selectq.  the 
I  isp  Machine  provides  cmnics  and  defselect:  see  page  30.) 

While  using  closures  (or  entities)  does  work,  it  has  several  serious  problems.  The  main 
problem  is  that  in  order  to  add  a  new  operation  to  a  system,  it  is  necessary  to  modify  a  lot  of 
code;  yon  have  to  find  .ill  the  types  that  understand  that  operation,  and  add  a  new  clause  to  the 
selectq.  The  problem  with  this  is  that  you  cannot  textually  separate  the  implementation  of  your 
new  operation  from  the  rest  of  the  system;  the  methods  must  be  interleaved  with  the  other 
operations  for  the  type.  Adding  a  new  operation  should  only  require  adding  1  isp  code;  it  should 
uot  require  modifying  l  isp  code. 

The  conventional  way  of  making  generic  operations  is  to  have  a  procedure  for  each  operation, 
which  has  a  big  selectq  for  all  the  types;  this  means  you  have  to  modify  code  to  avid  a  type. 

I  he  way  described  above  is  to  have  a  procedure  for  each  type,  which  has  a  big  selectq  for  all 
the  operations;  this  means  you  have  to  modify  code  to  add  an  operation.  Neither  of  these  has 
the  desired  property  that  extending  the  system  should  only  require  adding  code,  rather  than 
modifying  code. 

Closures  (and  entities)  are  also  somewhat  clumsy  and  crude.  A  far  more  streamlined, 
convenient,  and  powerful  system  for  creating  message-receiving  objects  exists;  it  is  called  the 
Flavor  mechanism.  With  flavors,  you  can  add  a  new  method  simply  by  adding  code,  without 
modifying  anything,  furthermore,  many  common  and  useful  tilings  to  do  are  very  easy  to  do 
with  flavors.  Ihe  rest  of  this  chapter  describes  flavors. 


1.6  Simple  Use  of  Flavors 

A  flavor,  in  its  simplest  form,  is  a  definition  of  an  abstract  type.  New  flavors  arc  created 
with  the  defflavor  special  form,  and  methods  of  die  flavor  are  created  with  the  defmethod  special 
form.  New  instances  of  a  flavor  arc  created  with  the  make  instance  function.  Ibis  section 
explains  simple  uses  of  these  forms. 

For  an  example  of  a  simple  use  of  flavors,  here  is  how  ihe  ship  example  above  would  be 
implemented. 
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(defflavor  ship  (x-position  y-position 

x-velocity  y-velocity  mass) 

() 

:gettable-i n stance-variables) 

(defmethod  (ship  :speed)  () 

(sqrt  (+  (~  x-velocity  2) 

( ~  y-velocity  2  ) ) ) ) 

(defmethod  (ship  nlirection)  () 

( atan  y-velocity  x-velocity)) 

The  code  above  creates  a  new  flavor.  The  first  subform  of  the  defflavor  is  ship,  which  is  the 
name  of  the  new  flavor.  Next  is  the  list  of  instance  variables;  ibex  are  the  live  that  should  be 
familiar  by  now.  The  next  subform  is  something  we  will  get  to  later.  I  he  rest  of  the  subforms 
arc  the  body  of  the  defflavor,  and  each  one  specifics  an  option  about  this  flavor.  In  our 
example,  there  is  only  one  option,  namely  :gettable- instance -variables.  I  his  means  that  for 

each  instance  variable,  a  method  should  automatically  be  generated  to  return  die  value  of  that 

instance  variable.  The  name  of  the  message  is  a  symbol  with  the  same  name  as  the  instance 

variable,  but  interned  on  the  keyword  package.  Thus,  methods  are  created  to  handle  the 

messages  :x- position,  :y- position  and  so  on. 

Hach  of  the  two  defmethod  forms  adds  a  method  to  the  flavor.  The  first  one  adds  a  handler 
to  the  flavor  ship  for  messages  named  .speed.  The  second  sublorm  is  die  lambda-list,  and  the 
rest  is  die  body  of  the  function  that  handles  the  :speed  message.  The  bod)  can  refer  to  or  set 
any  instance  variables  of  die  flavor,  the  same  as  it  can  with  local  variables  or  special  variables. 
When  any  instance  of  die  ship  flavor  is  invoked  with  a  first  argument  of  :direction,  the  body  of 
die  second  defmethod  will  be  evaluated  in  an  environment  in  winch  the  instance  variables  of 
ship  refer  to  the  instance  variables  of  this  instance  (the  one  to  which  the  message  was  sent).  So 
when  the  arguments  of  atan  arc  evaluated,  the  values  of  instance  variables  of  die  object  to  which 
die  message  was  sent  will  be  used  as  the  arguments,  atan  will  be  invoked,  and  die  result  it 
returns  will  be  returned  by  die  instance  itself. 

Now  we  have  seen  how  to  create  a  new  abstract  type:  a  new  flavor,  livery  instance  of  ibis 
flavoi  will  have  the  five  instance  variables  named  in  die  defflavor  form,  and  the  seven  methods 
we  have  seen  (five  dial  were  automatically  generated  because  of  the  :gettable  instance  -variables 
option,  and  two  that  we  wrote  ourselves).  The  way  to  create  an  instance  of  our  new  flavoi  is 
with  die  make-instance  function.  Here  is  how  it  could  be  used: 

(setq  my  ship  ( make - i ns tance  ’ship)) 

This  will  return  an  object  whose  printed  representation  is: 

0<SHIP  1373  12 10> 

(Of  course,  the  value  of  the  magic  number  will  vary:  it  is  not  interesting  anyway. )  I  lie 
argument  to  make-instance  is,  as  you  can  see.  the  name  of  the  flavor  to  be  instantiated. 
Additional  arguments,  not  used  here,  arc  iml  npiinns.  that  Is.  commands  to  (lie  flavor  of  which 
we  arc  making  in  instance,  selecting  optional  features.  Ibis  will  be  discussed  more  in  a  moment. 
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l;.xaininaiioii  of  the  flavor  we  have  defined  shows  that  ii  is  quite  useless  as  n  stands,  since 
there  is  no  way  to  set  am  of  the  parameters.  We  can  lix  this  up  easily .  by  putting  the 
:settable  instance  variables  option  into  the  defflavor  form.  I  his  opium  tells  defflavor  to 
generate  methods  for  messages  named  :set  x  position.  :set  y  position,  ami  so  on;  c.kIi  such 
method  takes  one  argument,  and  sets  the  corresponding  instance  vminblc  ic  the  given  value. 

Another  option  we  can  add  to  the  defflav/or  is  initable  instance  variables,  to  allow  us  to 
initialize  the  values  of  the  instance  variables  w  hen  an  instance  is  first  created,  initable  instance - 
variables  does  not  create  any  methods;  instead,  il  makes  ir.iihili:ii.'iuii  Amium/v  named  :x 
position.  :y -position,  etc.,  ilia  can  he  used  as  inii-option  arguments  to  make  instance  to 
initiali/e  the  corresponding  instance  variables.  Ihe  set  of  inn  options  are  sometimes  called  he 
inil-plisl  because  they  are  like  a  property  list. 

Here  is  the  improved  defflavor: 

(defflavor  ship  (x-position  y-position 

x-velocity  y  velocity  mass) 

() 

: gettable-i n stance -variables 
:settable-i n stance-variables 
: initable-i n stance-variables) 

All  wc  have  to  do  is  evaluate  this  new  defflavor.  and  the  existing  flavor  definition  will  be 
updated  and  now  include  the  new  methods  and  initialization  options.  In  fact,  the  instance  we 
generated  a  while  ago  will  now  be  able  to  accept  these  new  messages!  We  can  set  the  mass  of 
the  ship  we  created  by  evaluating 

(funcall  my-ship  ’:set-mass  3.0) 

and  the  mass  instance  variable  of  my-ship  will  properly  get  set  to  3.0.  If  you  want  to  play 
around  with  flavors,  it  is  useful  to  know  that  describe  of  an  instance  tells  you  the  flavor  of  the 
instance  and  the  values  of  its  instance  variables.  If  wc  were  to  evaluate  (describe  my-ship)  at 
this  point,  the  following  would  be  printed: 

0<SHIP  1373 12  10> ,  an  object  of  flavor  SHIP, 
has  instance  variable  values: 

X-POSITION:  unbound 

Y-POSITION:  unbound 

X-VELOCITY:  unbound 

Y-VELOCITY:  unbound 

MASS:  3 . 0 

Now  that  the  instance  variables  arc  "initable",  we  can  create  another  ship  and  initialize  some 
of  the  instance  variables  using  the  inil-plist.  l  et's  do  that  and  describe  the  result: 
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(sotq  her  ship  (make -instance  ‘ship  ' : x  position  0.0 

' : y  p o s i t i o n  2.0 
' : mass  3.5}) 

-=>  #<SII  I  P  1375652  1> 


( d e s c r i b e  her -ship) 

0<SHIP  1 3 7 5 6 o 2  1  > .  an  object  of  flavor  ‘HIP. 
has  instance  variable  values: 

X- POSITION:  0.0 

Y- POSIT  ION:  2.0 

X-VELOCITY:  unbound 

Y-VFIOCI 1 Y :  unbound 

MASS:  3.5 

A  flavor  can  also  establish  default  initial  values  for  instance  variables.  These  default  values  arc 
used  when  a  new  instance  is  created  if  the  values  are  not  initialized  any  mliei  way.  Hie  syntax 
for  specifying  a  default  initial  value  is  to  replace  the  name  of  the  instance  variable  In  a  list, 
whose  first  clement  is  the  name  and  whose  second  is  a  form  to  evaluate  to  produce  the  default 
initial  value.  For  example: 

(defvar  *defaultx  velocity*  2.0) 

(defvar  *def aul t-yveloci ty*  3.0) 

(defflavor  ship  ((x-position  0.0) 

( y  pos i t ion  0.0) 

(x-velocity  *default-x  ve  1  or  1  t.y  *  ) 

(y-velocity  *defaulty-velor.  ity*) 
mass ) 

O 

:  rjettable  -  i  n  stance-variables 
:  s  e  1 1  a  b  1  e  instance  variables 
: initable  instance-variables) 

(sotq  a u other-ship  (make-instance  'ship  ':x -position  3.4)) 

(describe  another  ship) 

(V  -  SHIP  14663643s.  an  object  of  flavor  SHIP, 
has  instance  variable  values: 

X  POS I  I  ION:  3.4 

Y  POSH  ION:  0.0 

X  VEI  OCHY:  2.0 

Y  VELOCITY:  3.0 

MASS:  unbound 

x  position  was  initiali/ed  explicitly,  so  the  default  was  ignoied  y  position  was  initiali/cd 
from  tlic  default  value,  which  was  0.0.  I  lie  two  velocity  instance  vat  tables  wen-  initialized  from 
their  default  values,  which  came  from  two  global  r  umbles,  mass  was  not  explicitly  mitiab/ed 
and  did  not  have  a  default  iiutiali/ation,  so  it  was  left  inbound. 
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There  are  many  oilier  options  that  can  lv  used  in  def flavor,  and  the  inn  uptiom  i.m  he  used 
more  flexibly  than  just  to  initialize  instance  \ariahles;  lull  details  are  given  laiei  u  this  chapter 
But  even  with  the  small  set  of  features  we  have  seen  so  lar.  it  is  easy  to  wine  object  01  tented 
programs. 


1.7  Mixing  Flavors 

Now  we  have  a  system  for  defining  message- receiving  objects  so  that  we  can  have  genenc 
operations.  If  we  want  to  crea  e  a  new  type  called  meteor  that  would  accept  the  same  generic 
operations  as  ship,  we  could  simply  write  anolhei  defflavor  and  two  itnne  defmethods  that 
looked  just  like  those  of  ship,  and  then  meteois  and  ships  would  both  accept  the  same 
operations,  ship  would  have  some  more  instance  variables  for  holding  attributes  specific  to  ships, 
and  some  more  methods  for  o|  orations  that  are  not  generic,  hut  are  only  defined  for  ships;  the 
same  would  be  true  of  meteor. 

However,  this  would  be  a  a  wasteful  thing  to  do.  The  same  code  has  to  be  repealed  in 
several  places,  and  several  instance  variables  have  to  be  repeated.  I  he  code  now  needs  to  be 
maintained  in  many  places,  which  is  always  undesirable.  Hie  power  of  Ilavors  (and  the  name 
"Ilavors")  comes  from  the  ability  to  mix  several  Ilavors  and  get  a  new  flavor.  Since  the 
functionality  of  ship  and  meteor  partially  overlap,  we  can  take  the  common  functionality  and 
move  it  into  its  own  flavor,  which  might  be  .ailed  moving  object.  We  would  define  moving  - 
object  the  same  way  as  we  defined  ship  in  the  previous  section.  Then,  ship  and  meteor  could 
he  defined  like  this: 

(defflavor  ship  ( eng i ne -power  number-of -passengers  name) 

( mov i ng  -objec  t ) 
tgettable- instance -variables) 

(uefflavor  meteor  { percent- i ron )  (moving-object) 

: i n i table- i nstance- var iabl es ) 

These  defflavor  forms  use  the  second  subform,  which  wc  ignored  previously.  The  second 
subform  is  a  list  of  flavors  to  be  combined  to  form  the  new  flavor;  such  flavors  arc  called 
components.  Concentrating  on  ship  for  a  moment  (analogous  things  arc  true  of  meteor),  wc  sec 
that  it  has  exactly  one  component  flavor:  moving  obiect.  It  also  has  a  list  of  instance  variables, 
which  includes  only  the  ship-specific  instance  variables  and  not  the  ones  that  it  shares  with 
meteor.  Hy  incorporating  moving -object,  the  ship  flavor  acquires  all  of  its  instance  variables, 
and  so  need  not  name  them  again.  It  also  acquires  all  of  moving -object  s  methods,  too.  So 
with  the  new  definition,  ship  instances  will  Mill  accept  the  :x  velocity  and  speed  messages,  and 
they  will  do  the  same  thing.  However,  the  :engine  power  message  will  also  he  understood  (and 
will  return  the  value  of  flic  engine  power  instance  variable). 

What  wc  have  done  here  is  to  take  an  abstract  type,  moving -object,  and  build  two  more 
specialized  and  powerful  abstract  types  on  top  of  it.  Any  ship  or  meteor  can  do  anything  a 
moving  object  can  do.  and  each  also  has  its  own  specific  abilities,  this  kind  of  building  can 
continue:  we  could  define  a  flavor  called  ship- with -passenger  that  was  built  on  top  of  ship, 
and  it  would  inherit  all  of  moving -obiect s  instance  variables  and  methods  as  well  as  ship's 
instance  variables  and  methods.  Tuithcrinorc.  the  second  sublomi  of  defflavor  can  be  a  list  of 
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several  compo-ients.  itk'.inmj;  that  tin-  new  llavoi  should  loml'inr  ii!  1 1 n  msi.nu.v-  uii.m.  .mb 
methods  ot  all  the  flavins  in  the  list,  as  will  .is  thv  one  //:* * v«  ll.nnis  .m  huili  mi  uni  -o  .>n 
All  the  eomponents  taken  together  lonn  i  hie  nee  m  ll  urns  \  ll.nm  is  luult  im  n  ns 
components.  its  eomponents  .omponeiiis  and  s.>  mi  \\i  sma.  nmv  us.  th.-  term  ' i<  nip.  in-nts" 

to  mean  the  immediate  eomponents  (the  oins  listed  m  the  doth, non  mb  . . .  nines  in  m  m  ill 

the  eomponenis  I  iiu  ludme  th.  eomponents  oi  the  immedi.ii  ■  ■  mop.. in  nt-.  and  s.  on)  <  \.  i ■  ills  n 

is  not  south  a  tree  sum  some  llavois  imehi  he  iompoh,i:  ilnmigh  mme  than  one  path  It  is 
really  a  directed  giaph.  it  e an  even  he  cyclic  ) 

I  he  order  u.  which  the  loinooncnts  an-  loinl-incd  to  toiin  a  llavoi  is  mipoitani  the  tiee  ot 
llavois  is  turned  into  an  older -el  Its!  In  pei  lot  linnet  a  /.  •/>  ,/mir.  walk  o|  ih.  dec 

including  non  terminal  nodes  I, -tor,  the  suhirees  tliev  head  and  ehmmaiimi  ilnplu ale-  hm 
example,  it  flavor  Is  immeihate  eomponenis  ate  flavor  ?  and  flavor  d  and  flavor  ;>  s 
components  are  flavor  4  and  flavor  b  and  flavm  3s  imiiponml  was  Havoi  -1  -Inn  die 
complete  lisi  ol' components  ol  flavor  1  uotiid  he: 

flavor  1.  flavor  ?,  flavor  4.  flavoi  !> .  flavor  l 
I  he  flavors  earliei  in  this  list  are  the  mme  specific .  less  h.isu  ones  m  oiu  example  ship  ,vith 
passengers  would  he  first  in  the  list  lollowed  In  ship  lollowed  In  moving  object  \  ti  .  r 

always  the  first  in  flic  list  of  ns  own  components.  Nome  thai  Havoi  4  dois  n.  t  appe  u  t.v  ■.  t 

this  list.  Only  die  first  occuneiico  of  a  llavoi  appears,  duplicates  ,uc  icmovcd  title  elm  m.idou 
of  duplii  •  s  is  done  during  the  walk;  if  tlieie  is  a  cvcle  m  the  ilm-i led  giaph  it  will  not  .  msc  a 
non  terminating  computation.) 

The  set  (if  instance  variables  for  the  new  limn  is  the  muon  of  all  the  sets  of  in  t:m  .- 
variables  in  all  the  component  flavors.  It  both  flavor  ?  .mil  flavor  3  mstain  <•  v.uialile- 

named  foo.  then  flavor  1  will  have  an  instance  v.uiable  nameii  tc.  >  id  .mv  methods  dm  in, ; 
to  foo  will  refer  to  this  same  instance  v.uiahic.  I  Inis  dillein  i  ••  , .  i.  r  ol  ,  Ha  m  <  ,m 
commmneaie  with  one  another  using  shared  instance  vanahles  il.,:  aliv  milv  mie  .  oirp, uirui 
ever  sets  the  variable,  and  the  others  onlv  look  ai  n  )  I  hr  delauli  mm  ,1  i.ilm  im  an  oist.nn  <• 
variable  comes  from  the  first  component  flavor  to  speuty  one 

Hie  wav  the  methods  ol  the  eomponents  air  lomhuieil  is  die  lu.m  ol  tin  do. a  ■ ,  ■ , •  t 1 1 
When  a  llavoi  is  dclmed.  a  single  tunc  lion,  called  a  >*mW.  is  mii-.iiiii  t  !  •  •:  <• ..  Ii 

message  supporic-d  hv  die  flavor.  Ibis  lom  lion  is  lonsimi  i.-d  out  ol  all  tin  nmili.  bs  r  i  iha 
message  from  all  the  components  of  die  ll.nm  Iheie  aie  in. oh  dilletent  wa,-  tfi.it  inetfo  .t .  .  an 
be  combined;  these  can  lie  selei  led  In  die  use:  when  a  llavoi  is  deluu  d  I  lie  uvi  i  r  ,iK«. 
create  new  limns  of  combination. 


I  heie  are  several  kinds  ol  methods,  but  so  t.u  die  oniv  kinds  ol  un  thuds  we  ham  mi  aie 
pruthin-  inetllods  I  lie  del. mil  wav  piim.nv  methods  air  iond'iind  is  dial  dl  Nil  dir  .  i : ! .  ,  ,  i  , 
provided  aie  ignored.  In  otlici  wmifs.  Ihe  loiii.'iiird  in.  dr  I  r>  simp1  1 ! i .  pom  u  .  m  ilio.f  i  iiu 
first  llavoi  to  piovule  a  piiin.uv  method  What  this  means  is  dial  il  mi  ,ur  si.uiinr  with  ;  d.i.m 

foo  and  building  a  flavm  b;ir  on  top  of  it.  thru  \oo  mu  oveimli  foo-.  m.  . .1. toi  i  m, hi 

providing  vom  own  method.  Your  method  will  he  called,  and  loo  s  will  uevei  he  i  nlleii 

Simple  overriding  is  often  useful:  if  vou  want  to  make  a  new  flavin  liar  that  h  ]u-.t  lor  foo 
except  that  it  reacts  completely  dillercntly  to  a  lew  messages,  then  this  will  wmk  Ih.wrvn  ottrn 
you  don't  want  to  completelv  overrule  the  base  llavois  (foos)  metlmil,  .omciimcs  mu  wait  to 

add  some  extia  things  to  be  done.  Ihis  is  where  eombmalion  ol  methods  is  used. 
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Ilk'  usual  wav  methods  .Hi'  iiiinhmril  is  ili.il  •  *n< -  II. um  piondcs  ,i  piim.in  method  .mil  oihci 
It. hois  p  1 1 1\  lilc  ././i  "i  "itlhihh  Ilk'  iili'  i  is  lll.il  Ilk  pi  I'll.il  \  method  Is  "ill  ill. up."  u!  llir  II '  .ill  ■ 

I'lMIICss  III  handling  ilk'  llk'ss.ll'i'  lilll  Hllli'l  ll.  Hills  |1|S|  \l.lli!  In  keep  ml.  H  l|  led  ill  I  ilk'  message 
W.ls  soil  HI  |HS|  IS  lilt  In  ill.  ilk'  pill  .'I  Ilk  .'PO  Ill'll  ,|SS.  I  Mil'll  mill  il  ..ll  h'.M,  Hi. I  I  >1 

ICspolISlI'lllll 

Will'll  llli'tllikls  III-  .  I'lIll'IIU'il  .1  sill'll  p'lil'H.  -Ill  ill.  •»!  Is  |.  >||  I  kl  .1  I. Sill-  III. ill  ilk'  tils! 

i'i  Miipi  uu'ii!  II. inn  lli.a  h.is  .HU'  \in  pi  1 1 1 1 1 1 1  iii  i'  1 1 1  *  ills  I'lli'ii.'iiii  in  ini  . .  Hk'iil  tl.niirs  no 

■pill  ili't.i  this  is  iiisi  iill.il  iii'  sail  above  li.u  1 1  *i  t  lil  Hiiiiiili'  loo's  pi  i'll.il  >  inillu.il  In  pioi  ullilg 
Us  mill  piimars  iik'lliuii. 

However.  mil  ill)  ill'll  lli'sl  Hllli'l  K  l  UiK  i'i  llk'llli  ills  III  p.n  in  lll.il  mu  i .  I P  ili'lllH'il  J.h'nUHl 

iik'lhmls  llk'i  i min  in  Inn  kinds  lun-ii  nut  *;//«  i  I  line  is  .1  .poi  i  d  mii.H  in  <l«j>f  method  (dr 
defining  sill  1 1  Ilk'll  li  'its  Ill'll'  is  .HI  example  nl  Ilk'  s', max  In  L'lic  ills'  ship  1 1 .  ll  i*l  all  at'lCI' 
ilaciiiHii  ii ul I u ul  Im  the  spoor)  message  I lu  lollouing  sun.ix  would  Ik’  used: 

(  da  I  mu  I  hull  (ship  :  a  f  t  »-•  t  spood)  () 

6oi/l  ) 


Non.  Hill'll  a  message  IS  soil  ll  Is  llaiullcd  Ik  a  Ik'n  lillli  Ill'll  i.illcd  tin  . d'un './  Illi'lllod 

1  lie  combined  iiiellii ul  Inst  i alls  all  ul  the  helme  daemons  ilien  the  piuiiaii  u;  iluul  tin'll  all  the 
attei  daeinuns  l  .uh  method  is  passed  the  same  aieumeiiis  dial  the  lomhmed  melliod  was  given, 
I  he  retmiied  i .lines  from  die  emiihined  method  aie  (he  i alius  leimiied  I'i  [he  pnm.uv  method: 
an>  values  fctiirned  Iioiii  die  daemons  are  ipioied  Helme  daemons  are  sailed  in  the  older  dial 
flavors  are  lomhmed  while  alto  daemons  aie  called  in  the  rmeise  oulei  In  olliei  words  if  vou 
build  bar  on  top  of  too.  men  bar's  helme- daemons  will  urn  helme  am  of  those  in  too.  and 
bars  atto  daemons  mil  run  after  an>  of  those  in  (oo. 

I  fie  reason  lor  this  order  is  to  keep  the  modul.uitv  order  correct  If  we  ovate  flavor  1  built 
mi  flavor  2:  then  u  should  not  mailer  what  flavor  2  is  limli  out  of  (fur  new  he  lore -daemons 
po  be  lore  all  those  nl  flavor  2.  and  our  new  alio  daemons  go  attei  all  those  ol  flavor  2.  Note 
that  it  vou  have  no  daemons  this  reduces  to  the  lmm  of  combination  described  above.  Ilte  most 
iceoiili  added  component  tl.noi  is  die  hiphest  level  ol  abstraction:  vou  build  a  hiplio -level  object 
on  lop  ol  a  lowo  level  obiccl  In  adding  new  components  to  the  front  I  lie  s,  max  loi  defining 
daemon  methods  mu  he  lound  m  die  deviiplion  ol  ilefmt'thod  below. 

lo  make  this  a  hit  more  clear,  lets  consido  a  simple  example  that  is  easi  to  plai  with:  the 
print  solf  melliod  I  lie  lisp  piuito  lie  die  punt  time  tu<n  see  sec  lions  IS.’  and  1X4  in  the 
I  isp  M.u  lime  Mann. ill  punts  nisi, tikes  ol  tl.nois  In  sending  Ihon  print  solf  u.i  s-.ai'es  I  lie  lirst 
argument  to  the  print  self  message  is  a  stream  (we  can  ipinue  the  others  1m  now),  and  the 
rococo  of  the  message  is  supposed  In  pnni  Us  pnnied  lepiesoiiaiioii  on  the  siieam  In  the  ship 
example  above  Ihe  icason  that  in  lances  ol  die  ship  llaioi  punted  Ihe  wav  (Inn  did  is  because 
the  ship  llaioi  was  m  tiialli  hull!  on  lop  ol  a  ceri  husk  llaioi  called  vnmlln  flavor:  this 
componeni  is  piouded  . iiitoiii.it ie .if I >  In  (Mtlavoi  ll  was  vanilla  flavors  print  self  method  that 
was  doing  the  printing  Now.  if  we  give  ship  Us  own  pimi.uv  melliod  tot  the  print  self 
message,  then  dial  mcihod  will  take  oiei  the  |oh  ol  punting  complctolv:  vanilla  flavor's  method 
will  not  he  called  .it  all  However,  d  we  give  ship  a  helme -daemon  melliod  loi  die  print-sell 
message  then  il  will  gel  invoked  holme  the  vanilla  flavor  message  and  so  wliaievei  it  pi  mis  s*.  ill 
appeal  tie  tore  what  vanilla  flavor  punts  So  we  mu  use  helot  e  daemons  to  add  prefixes  to  a 
printed  lepieseiitation  sumlaili.  attei  daemons  i an  add  stilhxcs 
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I  here  arc  other  ways  to  combine  methods  besides  daemons,  but  this  way  is  the  most 
common.  Hie  more  advanced  wavs  ol  wmihming  methods  aie  explained  in  .1  lalei  section:  see 
page  25.  Hie  vanilla -flavor  and  what  it  does  tor  >011  are  also  explained  later,  see  page  24. 


1.8  Flavor  Functions 

def flavor  Mturo 

A  flavor  is  defined  by  a  form 

(def flavor  //,  vor-mime  (nirl  viir2.  .  .  )  (/An/  /An.1.  .  .  ) 
opt!  ,ipi2 .  .  .  ) 

/Anoniimic  is  a  symbol  which  serves  to  name  this  flavor.  Ii  will  get  an  si. flavor  pioperty 
of  the  internal  data-strncnire  containing  the  details  of  the  flavin. 

(typep  t'bj).  wile:  <>/>/  is  an  instance  of  the  flavor  named  rA/ru/  lumn ,  will  utnin  the 
symbol  lliiwi'-thinh'.  (typep  u/>/  /A/io/u.m/t)  is  t  it  o/>/  is  an  instance  of  a  flavoi.  one  of 
whose  components  (possibly  itself)  is  thiuii-iui»'i\ 

Mirl ,  vur2,  etc.  are  the  names  of  the  instance- vaiiablcs  containing  the  local  state  for  (Ins 
flavor.  A  list  of  the  name  of  an  instance  vaiiable  and  .1  dciault  nntiali.ation  form  is  also 
acceptable:  the  initialization  form  will  be  evaluated  when  an  instance  ol  the  flavor  is 
created  if  no  other  initial  value  lot  the  \ .11  table  is  obtained  It  no  initialization  is 
specified,  the  variable  will  remain  unbound. 

fit ivl,  flav2,  etc.  are  the  names  of  the  component  flavors  out  ot  whu:i  this  flavor  is  built. 

I  he  features  of  those  flavors  are  mheiiied  as  desciibed  previously 

opil,  opi2.  etc.  are  options;  each  option  m.iv  be  eithei  a  kowoid  symbol  01  a  liw  of  a 
keyword  symbol  and  aigumenls.  I  he  options  to  ilolflavoi  aie  described  on  page  20 

•all  flavor  names*  I  unable 

I  Ins  is  a  list  of  the  names  of  all  the  Haims  that  have  vvci  been  dufflavor'ed. 

defmethod  M,u  .<> 

A  method,  that  is.  a  function  to  liar  lie  a  panic  ul.u  mesvtee  sent  to  an  instan.  c  of  a 
parttenlai  flavin,  is  defined  In  a  loun  anil  as 

(  de  fine  thud  ( fltnm  n  un,  <0  /ms/  i\pr  »u  u./iy)  UimhiLi  /iv7 
lunnl  fonn2 .  .  .  ) 

thnnriunn  is  a  symbol  which  is  (lie  name  ol  the  llavoi  which  is  to  irceive  the  method 
mi  lii<ui  n  pt  is  a  kevvvoiil  symbol  lor  tile  Ivpe  ot  nielliod  n  is  omitted  when  v  <  <  1 1  aie 
delimng  .1  pillliaiv  method.  wlltcll  is  the  usual  1  ase  ><ir  ewn  r.  a  kevwoicl  svmbol  which 
names  the  message  to  he  handled. 

I  he  meaning  ol  the  nu-ihinl  npr  depends  on  what  kind  <4  method  c  oiubm.ition  is  da  land 
for  tins  message  I  or  instance,  lor  daemons  bofoifi  and  alter  an  allowed  See  page 
tor  a  complete  desciiption  ot  method  types  and  the  wav  methods  aie  combined 

himlhlti  hsl  describes  the  aigumenls  and  "an x  v.ni.ihles"  o|  the  Imii  tion.  die  liai  .miutieui 
to  the  method,  wlm  It  is  the  message  kevwonl.  is  aulomaliialli  handled  and  so  il  is  not 
UK  lulled  111  the  i.nnl'.l,i  h\l  Note  that  methods  ill  iv  nol  have  Kijoolo  aigumenls.  1l1.1t  is 
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they  mtisi  ho  functions,  not  spiii.il  I’m  ms.  flnnl .  form?.  ok  .no  tho  linuiion  body  llio 
value  of  the  Iasi  form  is  returned. 

The  variant  form 

( defmel hod  ( thivin -inone  mewaye)  liinelivn) 
where  tunciion  is  a  symbol.  savs  dial  !hiu-i  n.wn  \  molded  lor  nitwi;.  is  ''uiuium.  a 
symbol  wlneh  names  a  function.  I  hat  fomlnm  mnsi  lake  appiopii.ite  .ugiimculs.  iho  liisi 
argument  is  the  message  keyword. 

If  you  redeline  a  method  that  is  already  defined,  the  old  definili  m  is  loplaeed  In  the  new 
one.  (inen  a  flavor,  a  message  name,  and  a  method  type  ihoio  mu  only  he  one 
limelion.  so  if  von  defiik  a  before  daemon  method  lor  the  foo  flavor  to  handle  Iho  bar 
message,  then  you  replace  the  previous  before-daemon:  howev-'i.  you  do  not  alleel  the 
primary  method  or  methods  of  any  other  type,  message  name  or  flavor. 

defmethod  actually  defines  a  symbol,  called  the  fl.ivarmcilnuf-s  nthot.  as  a  limelion.  and 
the  flavor  system  goes  through  that  symbol  to  call  the  method.  Sometimes  it  is  useful  to 
deal  with  such  a  symbol:  tor  example,  you  can  use  it  to  trace  a  method  with  trace  (see 
page  m  the  I  isp  Machine  Manual).  Ihc  llavoi  method -svmhi'l  is  lomied  hy 

eoneatenaimg  (with  hyphens)  the  llavor  name,  the  method  tvpe.  the  message  name,  and 
"method"  (for  example,  ship  x  position  method,  ship  after  y  velocity  method, 
ship  -  combined  -  mass  method,  etc.). 

fliaka*  Instance  flavor  name  tnii-opiianl  value  I  imt-option?  value?... 

Creates  and  returns  an  instance  of  the  specified  flavor.  Arguments  after  the  first  arc 
alternating  inn-option  keywords  and  aiguments  to  those  kev words.  I  hose  options  are  used 
to  initialize  instance  variables  and  to  select  arbitrary  options,  as  described  above.  If  the 
flavor  supports  the  init  message,  n  is  sent  to  the  ncwly-ucated  object  with  one  argument, 
the  init  p list.  Hits  is  a  disembodied  propertv  list  containing  the  mu -options  specified  and 
those  defaulted  from  die  flavors  .-default  init  plist  make  instance  is  an  easy  lo  cal! 
interface  to  instantiate  flavor,  lor  full  details  refei  to  that  function. 

Instantiate  flavor  flavor  name  initphst  ^optional  vetnl-  out  message- p 
return  iinhaiulleJ-  kevH'inh  area 

This  is  an  extended  veision  ol  make  instance  giving  vou  more  leatmes.  Note  that  it 
takes  the  init  plist  as  a  t  argument,  r.ithei  th  m  taking  a  Arest  argument  of  nut  options 
and  values. 

the  mil- plist  argument  must  he  a  disembodied  propertv  list  loci  of  a  Srest  atgumcnl 
will  do.  Beware1  lilts  properly  list  i.m  he  modified,  the  pioperties  li . >m  the  default  mil 
plist  are  putprop  cd  on  if  not  ahe.uly  present. 

In  the  event  that  init  methods  do  remprop  of  propeities  alicady  on  the  in  it  plist  (as 
opposed  to  simply  doing  got  ami  putprop).  then  the  mu  plist  will  get  rplacd'cd  I  his 
means  that  the  actual  list  of  options  will  he  meddled  It  also  means  that  loct  of  a  Arest 
argument  will  not  wotk;  the  c.ilhi  ol  instantiate  flavor  must  u>pv  its  icst  aiguinent  (c.g. 
with  append),  this  is  bemuse  rplard  is  not  , Plowed  on  Sn«.t  aigiunents. 


v 
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first,  it'  the  ll. hoi's  method-table'  .uul  other  mteni.il  inhumation  li.ne  not  been  computed 
or  .ire  not  up  to  d.ite.  ihc\  .ire  compuied  Ibis  may  t.ike  .1  stibst.niti.il  .uiiount  1 !  nine 
and  invoke  the  oompilei.  but  will  mils  happen  ome  loi  a  pnticiil.ii  ll.ntir  no  mallei  how 
main  instances  sou  make,  unless  you  change  something 

Next,  the  instance  vaiiables  are  initialled.  I  here  aie  se.eial  wavs  this  initialization  can 
happen,  ll  an  iiisI.uk e  v.uiable  is  devl.ned  iiuial  lc  in. I  a  kevvvord  with  the  same  spelling 
as  its  name  appears  in  'nii-ph\l.  11  is  sci  to  the  value  specified  aflci  that  keyword  II  an 
instance  v.uiable  does  not  get  inniah/ed  tins  wav  m.l  an  milt, ill/. ilion  Idrin  was  spec  died 
tor  it  in  a  delflavor  that  hum  is  evaluated  and  the  callable  is  set  to  the  result  I  he 
imtiali/alion  form  may  not  depend  on  anv  instance  vaiiables  inn  on  self.  1;  will  not  he 
evaluated  in  the  "inside"  environment  in  which  methods  aie  called.  II  an  instance  v.uiable 
does  not  get  iiiitinh/cd  eilhci  ot  these  wavs  11  will  be  left  unbound:  presumable  an  init 
method  should  initiah/e  it  (see  below)  Note  that  a  simple  empty  disembodied  pioperty 
list  is  (ml),  which  is  what  you  should  give  d  vou  want  an  einptv  mu  plisl.  II  you  use  nil. 
the  properly  list  ot  nil  will  he  used,  which  is  piob.ihly  not  wiiat  you  want. 

If  any  kevword  appeals  in  the  uui-pl.si  but  is  not  used  to  initialize  an  inst.uu  e  v.uiable 
and  is  not  dee!, tied  in  an  init  -  keywords  option  (see  page  .'’(I)  it  is  piesumed  to  be  a 
misspelling  If  the  riiwn-unfnmJIul-kn  no/i/v  aigument  is  not  supplied,  such  keywords  are 
complained  about  by  signalling  an  eiror  Hut  it  r,  iwn-uiihim.llai-ki  1  minis  is  supplied  non- 
nil.  .1  list  of  such  keywords  is  returned  as  the  second  value  ot  instantiate  flavor. 

Note  that  default  values  in  live  mii  p/nt  can  come  from  the  default  init  plist  option  tn 
defflavor.  See  page  20. 

If  the  wmhnil-mrsMwp  argument  is  supplied  and  non  nil.  an  i,,i»  message  is  sent  to  the 
newly -created  instance,  with  one  aigument.  the  mil  p!'\t  cjol  can  be  used  to  extract 
options  horn  (Ins  properly -IN.  I  ach  llavor  tint  needs  imtiali/alion  can  contiibule  an  init 
method,  by  delining  a  daemon. 

It  die  arra  argumeni  is  specified,  it  o  the  numhet  of  an  atea  tti  wht.lt  to  cons  the 
instance,  otheiwise  it  is  conse.1  in  the  default  area. 

dafwrapper  t/./cm 

I  Ins  is  It. my  and  ll  vou  don't  uiuli  isl.m.t  t  uni  should  skip  it. 

Sometimes  (he  wav  the  ll.Hoi  s.-.t.u.  n:d  -nos  tlv  no.  tin  vis  ol  dill'Metlt  llavois  (the 
daemon  v.siem)  is  not  powetlul  enough  It;  dial  (lolwtapiior  .an  be  us.  .1  to  define  a 
in.icto  win.  h  expaii.ls  into  code  wlinh  is  wiapp.d  n ■  1  > id  it'.-  m.oiatmu  o|  the  methods, 
lilts  is  b.-cl  explained  bv  an  ox. imp1.'  suppos.  v  in  uee.l-  .1  .1  I--  k  linked  dm  mg  the 
piocessim  ot  the  too  message  to  the  tr.tr  lla.ot  vb  !i  '  ■  k ,  .  two  ugum.nls  and  vou 
have  a  lock  hobbo/  -pe.ialloim  win  It  kii"#.  bow  n.  k  the  f.k  ( piesumal'ly  it 
geneiates  an  unwind  protect)  lock  hobbo/  need'-  to  -cc  the  lust  aigument  to  the 
message,  pel  haps  that  tells  it  wit. it  suit  ot  opeiation  is  going  to  he  performed  (read  or 
write) 
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(defwrapper  (Liar  :foo)  ((aryl  arg2)  body) 

’ ( 1 ock  f robboz  (self  aryl) 

.  .body') 

I  bo  use  of  ibo  body  macro  .iigimn  ni  prevents  iho  defwrappei’cd  in. imp  from  knowing 
the  exact  implementation  ami  allows  sexer.il  defwrapperx  liom  dilfcicnt  ll.ivois  to  he 
combined  properly. 

Nine  well  that  the  argument  variables,  argl  and  arg2.  are  not  referenced  with  comm. is 
before  them.  I  hose  mas  look  like  defmacro  "argument"  variables,  but  (lies  are  not. 
Those  variables  are  not  I  omul  at  the  time  the  defwrapper -defined  macro  is  expanded  and 
the  back-quoting  is  done;  rather  the  result  of  that  macro  expansion  and  back  quoting  is 
code  which,  when  a  message  is  sent,  will  bind  those  variables  to  the  aieuments  in  the 
message  as  local  variable;  of  the  combined  method. 

Consider  another  example.  Suppose  you  thought  you  wanted  a  :before  daemon,  but 
found  that  if  the  argument  wax  nil  you  needed  to  return  from  processing  the  message 
immediately,  without  executing  the  primary  method.  You  could  write  a  wrapper  such  as 
(defwrapper  (bar  :foo)  ((argl)  .  body) 

'(cond  ((null  argl))  ;Do  nothing  if  argl  is  nil 

( t  bijori'-code 
■  .body))) 

Suppose  you  need  a  variable  for  communication  among  the  daemons  for  a  particular 
message;  perhaps  the  .after  daemons  need  to  know  what  the  primary  method  did,  and  it 
is  something  that  cannot  be  easily  deduced  from  just  die  arguments.  You  might  use  an 
instance  variable  for  this,  or  yon  might  create  a  special  variable  which  is  bound  during 
die  processing  of  the  message  and  used  free  by  the  methods. 

(defv/ar  ♦communication*) 

(defwrapper  (bar  :foo)  (ignore  .  body) 

'(let  ( ( »communication*  nil)) 

.  .body)) 

Similarly  you  might  want  a  wrapper  which  puts  a  *crtch  around  the  processing  of  a 
message  so  that  any  one  of  the  methods  could  throw  out  in  the  event  of  an  unexpected 
condition. 

If  you  change  a  wrapper,  the  change  may  not  take  effect  automatically.  You  must  use 
recompile  flavor  with  a  third  argument  o!  nil  to  force  the  clfcct  to  propagate  into  the 
compiled  code  which  the  system  generates  to  implement  the  flavor.  I  he  reason  for  this  is 
that  the  flavor  system  cannot  reliably  tell  the  difference  between  reloading  a  file  containing 
a  wrapper  and  really  redefining  the  wrapper  to  be  different,  and  propagating  a  change  to 
a  wrapper  is  expensive.  1 1  Ills  may  be  fixed  in  the  future.] 

like  daemon  methods,  wrappers  woik  m  outsidc-in  order;  when  you  add  a  defwrapper 
to  a  flavor  limit  on  other  ll.ivois,  the  new  wrapper  is  placed  outside  any  wrappers  of  the 
component  fl.nois  llowevci.  a1!  wrappers  happen  before  any  daemons  happen.  When 
die  combined  method  is  built,  the  calls  to  the  before-daemon  methods,  primary  methods, 
anti  .iftcr -daemon  methods  ate  ill  placed  together,  and  then  the  wrappers  arc  wrapped 
around  them.  I  Inis,  if  a  component  llavor  defines  a  wrapper,  methods  added  by  new 
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flavors  will  execute  within  that  wrapper’s  context, 
self  Variable 

When  a  message  is  sent  to  an  object,  the  variable  self  is  automatically  bound  to  that 
object,  for  the  benefit  of  methods  which  want  to  manipulate  the  object  itself  (as  opposed 
to  its  instance  variables). 

f uncall  self  message  arguments... 

When  self  is  an  instance  or  an  entity,  (funcall  -  self  args...)  has  the  same  clfect  as 
(funcall  self  tags...)  cxce  u  that  it  is  a  little  faster  since  it  doesn't  have  to  re-establish  the 
context  in  which  the  instmec  variables  evaluate  correctly.  If  self  is  not  an  instance  (nor 
an  "entity",  sec  page  .10).  funcall -self  and  funcall  self  do  the  same  thing. 

When  self  is  an  instance,  funcall  -  self  will  only  work  correctly  if  it  is  used  in  a  method 
or  a  function,  wrapped  in  a  declare-flavor-instance-variables,  Unit  was  called  from  a 
method.  Otherwise  the  instance-variables  will  not  be  already  set  op. 

1  expr  - f uncal  1  - S8 1  f  message  arguments...  list- of- arguments 

1'his  function  is  a  cross  between  lexpr-funcal!  and  funcall  self.  When  self  is  an  instance 
or  an  entity,  (lexpr-funcall-self  tags...)  has  the  same  clfect  as  (lexpr  funcall  self  args...) 
except  Unit  it  is  a  little  faster  since  it  doesn't  have  to  re-establish  die  context  in  which  Ore 
instance  variables  evaluate  correctly.  If  self  is  not  an  instance  (nor  an  "entity",  sec  page 
.10).  (expr -funcall -self  and  lexpr- funcall  do  the  same  thing. 

declare- flavor- Instance -variables  Macro 

Sometimes  you  will  write  a  function  which  is  not  itself  a  method,  but  which  is  to  be 
called  by  methods  and  wants  to  be  able  to  access  die  instance  ...riablcs  of  the  object  self. 
The  form 

(declare-flavor -  instance-variables  ( 'flavor- name ) 
function-definition ) 

surrounds  the  function-definition  with  a  declaration  of  the  instance  variables  for  the 
specified  flavor,  which  will  make  them  accessible  by  name.  Currently  this  works  by 
declaring  them  as  special  variables,  but  tins  implementation  may  be  changed  in  the  future. 
Note  that  it  is  only  legal  to  call  a  function  defined  Uiis  way  while  executing  inside  a 
method  for  an  object  of  the  specified  flavor,  or  of  some  flavor  built  upon  it. 

recomplle-flavor  flavor- name  &optioiial  single  message  (usc-olJ-combincd-mclhods  \.) 
(do-dependents  \) 

Updates  the  internal  data  of  the  flavor  and  any  flavors  that  depend  on  it.  It  single¬ 
message  is  supplied  mm  nil.  only  the  methods  liu  that  message  are  changed.  The  system 
does  this  when  you  define  a  new  method  that  did  not  previously  exist.  If  use-old- 
combined- met  hods  is  t,  then  the  existing  combined  method  functions  will  be  used  if 
possible.  New  ones  will  only  be  generated  if  the  set  of  methods  to  be  ealled  has  changed, 
l  itis  is  the  default.  If  use-old-combined-mcthods  is  nil.  automatically  -generated  functions  to 
call  multiple  methods  or  to  contain  code  generated  by  wrappers  will  he  regenerated 
unconditionally.  If  you  change  a  wrapper,  you  must  do  recompile  flavor  with  third 
argument  nil  in  order  to  make  the  new  wrapper  take  ellect.  If  do-dependents  is  ml,  only 
the  specific  flavor  you  specified  will  be  recompiled.  Normally  it  and  all  flavors  that 
depend  on  it  will  be  recompiled. 
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recompile -flavor  only  affects  flavors  that  have  already  been  compiled.  I'ypicall)  ibis 
means  it  affects  flavors  that  have  been  instantiated,  but  does  not  bother  with  mixins  (see 
page  23). 

compile-flavor -methods  Macro 

The  form  (compile-flavor-methods  flavor  natm- 1  flavor-name- 1 placed  m  a  lile  to  be 
compiled,  will  cause  the  compiler  to  include  the  automatically  generated  combined 
methods  for  the  named  flavors  in  the  resulting  qfasl  file,  provided  all  of  the  necessary 
flavor  definitions  have  been  made.  Use  of  compile -flavor -methods  for  all  flavors  that 
arc  going  to  be  instantiated  is  recommended  to  eliminate  the  tued  to  call  the  compiler  at 
run  time  (the  compiler  will  still  he  called  if  incompatible  changes  have  been  made,  such 
as  addition  or  deletion  of  methods  that  must  be  called  by  a  combined  method). 

get-handler-for  object  message 

Given  an  object  and  a  message,  will  return  that  object’s  method  for  that  message,  or  nil 
if  it  has  none.  When  object  is  an  instance  of  a  flavor,  this  function  can  be  useful  to  find 
which  of  that  flavor's  components  supplies  the  method,  if  you  get  back  a  combined 
method,  you  can  use  the  last  Combined  Methods  editor  command  (page  31)  to  find  out 
what  it  docs. 

This  function  can  be  used  with  other  things  than  flavors,  and  has  an  optional  argument 
which  is  not  relevant  here. 

8ym#val-1n-1nstance  instance  symbol  &optional  no-error-p 

This  function  is  used  to  find  the  value  of  an  instance  variable  inside  a  particular  instance. 
Instance  is  the  instance  to  be  examined,  and  symbol  is  the  instance  variable  whose  value 
should  he  returned.  If  there  is  no  such  instance  variable,  an  error  is  signalled,  unless  no- 
error p  is  non-nil  in  which  case  nil  is  returned. 

set- In- Instance  instance  symbol  value 

1'his  function  is  used  to  alter  the  value  of  an  instance  variable  inside  a  particular  instance. 
Instance  is  the  instance  to  be  altered,  symbol  is  the  instance  variable  whose  value  should 
be  set,  and  value  is  the  new  value.  If  there  is  no  such  instance  variable,  an  error  is 
signalled. 

si : descrlbe-f lavor  Jlavorname 

This  function  prints  out  descriptive  information  about  a  flavor;  it  is  self-explanatory.  An 
important  tiling  it  tells  you  that  can  be  hard  to  figure  out  yourself  is  the  combined  list  of 
component  flavors;  this  list  is  what  is  printed  after  flic  phrase  "and  directly  or  indirectly 
depends  on". 

si :*f lavor -comp  11  at  Ions* 

This  variable  contains  a  history  of  when  the  flavor  mechanism  invoked  the  compiler.  It  is 
a  list;  elements  toward  the  front  of  the  list  represent  more  recent  compilations.  Hlcmcnts 
arc  typically  of  the  form 

(  :  method  flavor  name  type  message- name) 
and  type  is  typically  .combined. 
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You  may  setq  this  variable  to  nil  at  any  time;  for  instance  before  loading  some  liles  that 
you  suspect  may  have  missing  or  obsolete  compile-flavor- methods  in  them. 


1.9  Defflavor  Options 

There  are  quite  a  few  options  to  defflavor.  They  are  all  described  here,  although  some  are 
for  very  specified  purposes  and  not  of  interest  to  most  users.  |;ach  option  can  be  written  in  two 
forms;  either  the  keyword  by  itself,  ora  list  of  the  keyword  and  "arguments"  to  that  keyword. 

Several  of  these  options  declare  things  about  instance  variables.  These  options  can  be  given 
with  arguments  which  are  instance  variables,  or  without  any  arguments  in  which  case  they  refer  to 
all  of  the  instance  variables  listed  at  the  top  of  the  defflavor.  This  is  mu  necessarily  all  die 
instance  variables  of  tire  component  flavors;  just  the  ones  mentioned  in  this  flavor's  defflavor. 
When  arguments  are  given,  thev  must  be  instance  variables  that  were  listed  at  the  top  of  the 
defflavor;  otherwise  they  are  as  .timed  to  be  misspelled  and  an  error  is  signalled.  It  is  legal  to 
declare  things  about  instance  variables  inherited  from  a  component  flavor,  but  to  do  so  you  must 
list  these  instance  variables  explicitly  in  the  instance  variable  list  at  the  top  of  die  defflavor. 

:gettable-  instance  -  variables 

Hnables  automatic  generation  of  methods  for  getting  the  values  of  instance  variables.  The 
message  name  is  the  name  of  the  variable,  in  die  keyword  package  (i.e.  put  a  colon  in 
front  of  it.) 

isettable  -  instance  -  variables 

Hnables  automatic  generation  of  methods  for  setting  the  values  of  him. nice  variables,  llic 
message  name  is  ":set-”  followed  by  die  name  of  the  variable.  All  settable  instance 
variables  arc  also  automatically  made  gctlable  and  initable. 

:i  nitable  -  instance  -  variables 

The  instance  variables  listed  as  arguments,  or  all  instance  variables  listed  in  ibis  defflavor 
if  the  keyword  is  given  alone,  are  made  initable.  This  means  that  they  can  he  initialized 
through  use  of  a  keyword  (a  colon  followed  by  the  name  of  the  v.uiahle)  as  an  initoption 
argument  to  make -instance. 

anit-keywords 

The  arguments  are  declared  to  he  keywords  in  the  iniiuh/.ition  propci ty  list  which  are 
processed  by  this  flavor’s  :init  methods  I  his  is  just  used  by  error-checking  which  looks 
for  entries  (presumably  misspelled)  in  the  initialization  property -list  which  are  not  bandied 
by  any  component  flavor  of  die  object  being  created,  neither  as  mitable-instanco- vai tables 
nor  as  init-keywords. 

:default  init-plist 

The  aignments  are  ahem. King  keywords  and  value  loin's,  like  a  property-list.  When  tile 
flavor  is  instantiated,  these  properties  and  values  nc  pm  into  the  init-plist  unless  already 
present.  This  allows  one  component  flavor  to  default  an  option  to  .  in >t her  component 
flavor.  The  value  forms  are  only  evaluated  when  and  if  thev  aie  used,  l  or  example, 

( idefaultinitplist  : f rob -array 

(make-array  nil  ’an  q  100)) 

would  provide  a  default  "froh  array"  for  any  instance  lor  whn.li  the  user  did  not  provide 
one  explicitly. 
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:required -instance  variables 

Declares  that  any  flavor  incorporating  this  one  which  is  instantiated  mio  an  (ihjca  must 
contain  the  spec i lied  instance  variables.  An  error  occurs  if  there  is  an  attempt  to 
instantiate  a  lluvor  that  iiicoiporates  this  one  i!  it  does  not  have  these  in  its  set  o<  instance 
vaiiahles.  Note  that  this  option  is  not  one  of  those  which  .hecks  the  spelling  of  its 

arguments  in  the  wav  deseiibed  at  the  .tail  of  this  section. 

Required  instance  variables  may  he  freely  accessed  In  methods  just  like  normal  instance 
variables.  The  difference  between  listing  instance  variables  here  and  listing  them  at  the 
front  of  the  defflavor  is  that  the  latter  declares  that  this  llavor  'owns"  those  variables  and 
will  rake  care  of  initiate  mg  them,  while  the  lormcr  declares  that  this  llavor  depends  cm 

those  variables  but  that  :0111c  other  llavor  must  he  provided  to  manage  them  and  whatever 

features  they  imply. 

required  methods 

I'he  arguments  arc  names  of  messages  which  any  flavor  incorporating  this  one  must 
handle.  A11  error  occurs  if  there  is  an  attempt  to  instantiate  such  a  llavor  and  it  is  lacking 
a  method  for  one  of  these  messages,  'typically  this  option  appears  in  the  defflavor  lot  a 
base  flavor  (see  page  23). 

ancluded  flavors 

I  he  arguments  are  names  of  flavors  to  be  included  in  this  llavor.  I  he  difference  between 
declaring  flavors  here  and  declaring  them  at  the  top  of  the  defflavor  is  that  when 
component  flavors  arc  combined,  all  the  included  flavors  come  after  all  the  regular  flavors, 
finis  included  flavors  act  like  defaults.  Tor  an  example  of  the  use  of  included  flavors, 
consider  the  ship  example  given  earlier,  and  suppose  we  want  to  define  a  relativity  -tnixin 
which  increases  the  mass  dependent  on  the  speed.  We  might  write, 

(defflavor  relativity-mixin  ()  (moving-object)) 

(defmethod  (relativity-mixin  :mass)  () 

(//  mass  (sqrt  (-  1  ("  (//  (fun call-self  ’ : speed) 

*speed-of -  light*) 

2))))) 

but  this  would  lose  because  any  flavor  that  bad  relativity-mixin  as  a  component  would  get 
moving -object  right  after  it  in  its  component  list.  As  a  base  flavor,  moving -object 
should  be  last  in  the  list  of  components  so  that  other  components  mixed  in  can  replace  its 
methods  and  so  that  daemon  methods  combine  in  the  right  order.  So  instead  we  write, 
(defflavor  relativity-mixin  ()  () 

(  :  included-f lavors  moving-object)) 
which  allows  relativity  mixin's  methods  to  access  moving  object  instance  variables  such  as 
mass  (the  rest  mass),  but  docs  not  specify  a  place  lor  moving  object  m  the  list  of 
components.  (Actually  it  puts  it  at  the  end.  where  it  will  usually  be  eliminated  as  a 
duplicate.) 

no  vanilla -flavor 

Unless  tins  option  is  specified,  si: vanilla  flavor  ts  included  (in  the  sense  of  the 
included  flavors  option),  vanilla  flavor  provides  some  default  methods  for  the  print- 
self.  :dcscribe,  which  operations.  get  handler  for.  eval  inside- yourself,  and 
funcall  inside  yourself  messages.  See  page  24. 

default  handler 

lire  argument  is  the  name  of  a  function  which  is  to  he  called  when  a  message  is  received 
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for  which  there  is  no  method.  It  will  he  called  with  whatever  arguments  the  instance  was 
called  with,  including  the  message  name;  whatever  values  it  returns  will  be  returned.  If 
this  option  is  not  specified  on  any  component  flavor,  it  defaults  to  a  function  which  will 
signal  an  error. 

tordered  -  instance  -  variables 

This  option  is  mostly  for  esoteric  internal  system  uses.  The  arguments  arc  names  of 
instance  variables  which  must  appear  first  (and  in  this  order)  in  all  instances  of  this  flavor, 
or  any  flavor  depending  on  this  flavor.  This  is  used  for  instance  variables  which  arc 
specially  known  about  by  microcode,  and  in  connection  with  the  :outside -accessible - 
instance-variables  option.  If  the  keyword  is  given  alone,  the  arguments  default  to  tire 
list  of  instance  variables  given  at  die  top  of  ihis  defflavor. 

:outside  -  accessible  -  instance  -  variables 

The  arguments  are  instance  variables  which  arc  to  be  accessible  from  "outside"  of  this 
object,  that  is  from  functions  other  than  methods.  A  macro  (actually  a  defsubst)  is 
defined  which  takes  an  object  of  this  flavor  as  an  argument  and  returns  the  value  of  the 
instance  variable;  sett  may  be  used  to  set  the  value  of  the  instance  variable.  The  name 
of  the  macro  is  the  name  of  the  flavor  concatenated  with  a  hyphen  and  the  name  of  the 
instance  variable.  T  hese  macros  are  similar  to  the  accessor  macros  created  by  defstruct 
(see  chapter  17  of  the  L.isp  Machine  Manual.) 

This  feature  works  in  two  diffc.ent  ways,  depending  on  whether  die  instance  variable  has 
been  declared  to  have  a  fixed  slot  in  all  instances,  via  die  :ordered- instance  variables 
option. 

If  the  variable  is  not  ordered,  the  position  of  its  value  cell  in  the  instance  will  have  to  be 
computed  at  run  time.  T  his  takes  noticeable  time,  although  less  than  actually  sending  a 
message  would  take.  An  error  will  be  signalled  if  the  argument  to  the  accessor  macro  is 
not  an  instance  or  is  an  instance  which  docs  not  have  an  instance  variable  with  the 
appropriate  name.  However,  there  is  no  error  check  that  the  flavor  of  the  instance  is  die 
flavor  the  accessor  macro  was  defined  for,  or  a  flavor  built  upon  that  flavor.  This  error 
check  would  be  too  expensive. 

If  die  variable  is  ordered,  die  compiler  will  compile  a  call  to  die  accessor  macro  into  a 
subprimitivc  which  simply  accesses  that  variable’s  assigned  slot  by  number.  This 
subprimitivc  is  only  3  or  4  times  slower  than  car.  1'he  only  error-checking  performed  is 
to  make  sure  diat  die  argument  is  really  an  instance  and  is  really  big  enough  to  contain 
dial  slot.  There  is  no  check  diat  the  accessed  slot  really  belongs  to  an  instance  variable  of 
the  appropriate  name.  Any  functions  that  use  these  accessor  macros  will  have  to  be 
recompiled  if  the  number  or  order  of  instance  variables  in  the  flavor  is  changed.  T  he 
system  will  not  know  automatically  to  do  this  recompilation.  II  you  aren't  very  careful, 
you  may  forget  to  recompile  something,  and  have  a  vciv  hard-to  find  bug.  because  of 
tiiis  problem,  and  because  using  diese  macros  is  less  elegant  dian  sending  messages,  die 
use  of  this  option  is  discouraged.  In  any  case  the  use  of  these  accessor  macros  should  be 
confined  to  die  module  which  owns  die  flavor,  and  die  "general  public"  should  send 
messages. 

rselect- method  -  order 

This  is  purely  an  efficiency  hack  due  to  the  fact  that  currently  the  method-table  is 
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searched  linear!)  when  .1  message  is  sent.  Ihe  arguments  are  names  of  messages  which 
are  frequently  used  or  for  which  speed  is  important.  Their  methods  are  moved  to  the 
front  of  the  method  table  so  that  they  are  accessed  more  quickly. 

:method  -combination 

Declares  the  way  that  methods  from  different  flavors  will  be  combined.  I'ach  "argument" 
to  this  option  is  a  list  (type  order  message l  messaged ...).  Message! .  messaged,  etc.  arc 
names  of  messages  whose  methods  are  to  be  combined  in  die  declared  fashion,  type  is  a 
keyword  which  is  a  defined  type  of  combination:  sec  page  25.  Order  is  a  keyword  whose 
interpretation  is  up  to  ly  «>;  typically  it  is  eidicr  :base- flavor -first  or  :base- flavor  last. 

Any  component  of  a  flavor  may  specify  the  type  of  method  combination  to  be  used  for  a 
particular  message.  If  no  component  specifies  a  type  of  method  combination,  then  the 
default  type  is  used,  namely  :daemon.  If  more  than  one  component  of  a  flavor  specifies 
it,  dicn  they  must  agree  on  die  specification,  or  else  an  error  is  signalled. 

:documentation 

T  he  list  of  arguments  to  this  option  is  remembered  on  die  flavor's  property  list  as  the 
:documentation  property.  The  (loose)  standard  for  what  can  be  in  this  list  is  as  follows; 
this  may  be  extended  in  the  future.  A  string  is  documentation  on  what  the  flavor  is  for; 
this  may  consist  of  a  brief  overview  in  the  first  line,  then  several  paragraphs  of  detailed 
documentation.  A  symbol  is  one  of  die  following  keywords: 

■.mixin  A  flavor  that  you  may  want  to  mix  with  others  to  provide  a  useful 

feature. 

:essential- mixin 

A  flavor  that  must  be  mixed  in  to  all  flavors  of  its  class,  or  inappropriate 
behavior  will  ensue. 

dowlevel-  mixin 

A  mixin  used  only  to  build  other  mixins. 
combination  A  combination  of  flavors  for  a  specific  purpose. 

:special- purpose 

A  flavor  used  for  some  internal  or  kludgey  purpose  by  a  particular 
program,  which  is  not  intended  for  general  use. 

This  documentation  can  be  viewed  with  the  shdescribe-  flavor  function  (sec  page  19)  or 
the  editor's  Meta-X  Describe  Flavor  command  (sec  page  30). 

1.10  Flavor  Families 

'Die  following  organization  conventions  arc  recommended  for  all  programs  that  use  flavors. 

A  base  flavor  is  a  flavor  that  defines  a  whole  family  of  related  flavors,  all  of  which  will  have 
that  base  flavor  as  one  of  their  components.  Typically  the  base  flavor  includes  things  relevant  to 
the  whole  family,  such  as  instance  variables,  required- methods  and  required -instance - 
variables  declarations,  default  methods  for  certain  messages,  :method -combination  declarations, 
and  documentation  on  the  general  protocols  and  conventions  of  the  family.  Some  base  flavors  are 
complete  and  can  be  instantiated,  but  most  arc  not  mstanlialablc  and  merely  serve  as  a  base  upon 
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which  lo  build  oilier  flavors.  I  hc  base  llavoi  lor  die  /on  family  is  often  named  htisic-loo. 

A  mixin  flavor  is  .1  flavor  dial  defines  one  pariiailar  le.it u re  ol  an  ihjecl.  A  mixin  cannot  be 
instantiated,  because  it  is  not  a  complete  description.  1  ach  module  or  feature  of  a  program  is 
defined  as  a  separate  mixin.  a  usable  flavor  can  be  constructed  In  choosing  the  mixins  for  the 
desired  characteristics  and  combining  them,  along  widi  the  appropriate  base  flavor,  fly  organizing 
your  flavors  this  way.  you  keep  separate  features  in  separate  flavors,  and  you  can  pick  and  choose 
among  diem.  Sometimes  the  order  of  combining  mixins  docs  not  matter,  but  often  it  docs, 
because  the  order  of  flavor  combination  controls  the  order  in  which  daemons  are  invoked  and 
wrappers  are  wrapped.  Such  order  dependencies  would  be  documented  as  part  of  the  conventions 
of  the  appropriate  family  of  11;  vors.  A  mixin  flavor  that  provides  the  mumble  feature  is  often 
named  mumble- mixin. 

If  you  arc  writing  a  program  that  uses  someone  else's  facility  to  do  something,  using  that 
facility's  flavors  and  methods,  your  program  might  still  define  its  own  flavors,  in  a  simple  way. 
I  he  facility  might  provide  a  base  flavor  and  a  set  of  mixins.  and  the  caller  can  combine  these  in 
various  combinations  depending  on  exactly  what  it  wants,  since  the  facility  probably  would  not 
provide  all  possible  useful  combinations.  I ■'.vcn  if  your  private  flavor  has  exactly  the  same 
components  as  a  pre-existing  flavor,  it  can  still  be  useful  since  you  can  use  its  default  init-plist 
(sec  page  20)  to  select  options  of  its  component  flavors  and  you  can  define  one  or  two  methods  to 
customize  it  "just  a  little". 

1.11  Vanilla  flavor 

Unless  you  specify  otherwise  (with  the  :no- vanilla -flavor  option  to  defflavor),  every  flavor 
includes  the  "vanilla"  flavor,  which  has  no  instance  variables  bin  provides  some  basic  useful 
methods.  Thus,  nearly  every  instance  may  be  assumed  to  handle  the  following  messages, 

: print-self  stream  prindepth  slash ifyp 

The  object  should  output  its  printed-representation  to  a  stream.  The  printer  sends  this 
message  when  it  encounters  an  instance  or  an  entity.  The  arguments  are  the  stream,  die 
current  depth  in  list-structure  (for  comparison  with  prinlevel).  and  whether  slash ilicatinn  is 
enabled  (prinl  vs  princ:  see  page  154  in  flic  l  isp  Machine  Manual).  Vanilla-flavor 
ignores  the  last  two  arguments,  and  prints  something  like  #  <flavornamc  octal  uddress>. 
The  flavor  name  tells  you  what  type  of  object  il  is.  and  (he  octal-address  allows  you  lo  tell 
different  objects  apart  (provided  the  garbage  collector  doesn’t  move  them  behind  your 
back). 

tdescrlbe 

The  object  should  describe  itself,  printing  a  description  onto  the  standard -output  stream. 
The  describe  function  sends  this  message  when  it  encounters  an  instance  or  an  entity. 
Vanilla-flavor  outputs  the  object,  the  name  of  its  flavor,  and  the  names  and  values  of  its 
instance- variables,  in  a  reasonable  format. 
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:wh1ch-oparat1ons 

The  object  should  return  a  list  of  the  messages  it  can  handle.  Vanilla-ll.ivor  genet. itos  the 
list  once  per  llavor  and  remembers  it.  minimizing  rousing  and  eompute  time.  If  a  new 
method  is  added,  the  list  is  regenerated  the  nest  lime  someone  asks  for  it. 

:get  handler  for  operation 

I'he  object  should  return  the  method  it  uses  to  handle  operation.  If  it  has  no  handler  for 

that  message,  it  should  return  nil.  This  is  like  the  get -handler  for  function  (see  page 

ff),  but,  of  course,  you  can  only  use  it  on  objects  known  to  accept  messages. 

:eval  Inside  yourself  form 

I  he  argument  is  a  form  which  is  evaluated  in  an  environment  in  which  special  variables 
with  the  names  of  the  instance  variables  are  bound  to  the  values  of  the  instance  variables. 
It  works  to  setq  one  of  these  special  variables;  the  instance  variable  will  be  modified. 
Ibis  is  mainly  intended  to  be  used  for  debugging.  An  especially  useful  value  of  firm  is 
(break  t).  this  gets  you  a  1  isp  top  level  loop  inside  the  environment  of  the  methods  of 

the  llavor.  allowing  you  to  examine  and  alter  instance  variables,  and  run  functions  that 

use  the  instance  variables. 

rfuncall  Inslde-yourself  function  &rest  args 

Junction  is  applied  to  arps  in  an  environment  in  which  special  variables  with  the  names  of 
the  instance  variables  are  bound  to  the  values  of  the  instance  variables.  It  works  to  setq 
one  of  these  special  variables;  the  instance  variable  will  be  modified.  Ibis  is  mainly 
intended  to  be  used  for  debugging. 


1.12  Method  Combination 

As  was  mentioned  earlier,  there  are  many  ways  to  combine  methods,  flic  way  wc  have  seen 
is  called  the  :daemon  type  of  combination.  To  use  one  of  the  01110111,  you  use  tbc  unethod- 
combination  option  to  defflavor  (see  page  23)  to  say  that  all  die  methods  for  a  certain  message 

to  this  llavor,  or  a  flavor  built  on  it,  should  be  combined  in  .1  certain  way. 

Hie  following  types  of  method  combination  arc  supplied  by  the  system.  It  is  possible  to 
define  your  own  types  of  method  combination;  for  information  on  this,  sec  the  code.  Note  that 
for  most  types  of  method  combination  other  than  aln.en  on  you  must  define  the  order  in  which 
the  methods  arc  combined,  cither  :base  flavor  first  or  :base -flavor -last.  I11  this  context,  base- 
flavor  means  the  last  clement  of  the  flavor's  fully -expanded  list  of  components. 

Which  method  type  keywords  are  allowed  depends  on  die  type  of  method  combination 
selected.  Many  of  diem  allow  only  untyped  methods.  There  are  also  certain  method  types  used 
for  internal  purposes. 

:daemon  This  is  the  default  type  of  method  combination.  All  the  :before  methods  are 
called,  then  the  primary  (untyped)  method  for  the  outermost  flavor  that  has  one  is 

called,  then  all  the  :after  mcdiods  are  called.  I  he  value  returned  is  the  value  of 

the  primary  mcdiod. 

:progn  All  the  methods  arc  called,  inside  a  progn  special  form.  No  typed  methods  arc 

allowed.  This  means  ih.it  .ill  of  the  methods  are  called,  and  the  result  of  the 
combined  method  is  whatever  the  last  of  the  methods  returns. 
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:or  All  the  methods  arc  called,  inside  an  or  special  form.  No  typed  methods  are 

allowed.  This  means  dial  each  of  the  methods  is  called  in  turn.  If  a  method 
returns  a  non-nl  value,  dial  value  is  returned  and  none  of  the  rest  of  the 
methods  arc  called;  otherwise,  the  next  method  is  called.  In  other  words,  each 
method  is  given  a  chance  to  handle  the  message;  if  it  doesn't  want  to  handle  the 
message,  it  should  return  nil,  and  die  next  method  will  get  a  chance  to  try. 

;and  All  the  methods  are  called,  inside  an  and  special  form.  No  typed  methods  are 

allowed.  The  basic  idea  is  much  like  :or;  see  above. 

:list  Calls  all  the  methods  and  returns  a  list  of  their  returned  values.  No  typed 

mcdiods  arc  allowed. 

:inverse-list  Calls  each  method  with  one  argument;  these  arguments  arc  successive  elements  of 

the  list  which  is  the  sole  argument  to  die  message.  No  typed  methods  arc 

allowed.  Returns  no  particular  value.  If  the  result  of  a  disHombined  message  is 
sent  back  with  in  anverse  list-combined  message,  with  the  same  ordering  and 
with  corresponding  method  definitions,  each  component  flavor  receives  die  value 
which  came  from  that  flavor. 

Here  is  a  table  of  all  die  mcdiod  types  used  in  die  standard  system  (a  user  can  add  more,  by 
defining  new  forms  of  mcdiod-combination). 

(no  type)  If  no  type  is  given  to  defmethod,  a  primary  mediod  is  created.  ITiis  is  the  most 
common  type  of  method. 

:before 

:after  Ihcse  arc  used  for  die  before-daemon  and  after-daemon  mcdiods  used  by 

:daemon  mcdiod-combination. 

:default  If  there  arc  no  untyped  mcdiods  among  any  of  the  flavors  being  combined,  dicn 

die  idefault  mcdiods  (if  any)  are  treated  as  if  they  were  untyped.  If  dicre  are  any 
untyped  methods,  die  .default  methods  arc  ignored. 

Typically  a  base-flavor  (sec  page  23)  will  define  some  default  mcdiods  for  certain 
of  the  messages  understood  by  its  family.  When  using  the  default  kind  of 
mcdiod-combination  these  default  methods  will  not  be  called  if  a  flavor  provides 
its  own  method.  Hut  with  certain  strange  forms  of  method-combination  (:or  for 
example)  die  base-flavor  uses  a  :default  method  to  achieve  its  desired  effect. 

.wrapper  Used  internally  by  defwrapper. 

:combined  Used  internally  for  automatically-generated  combined  mcdiods. 

The  most  common  form  of  combination  is  :daemon.  One  thing  may  not  be  clear:  when  do 
you  use  a  : before  daemon  and  when  do  you  use  an  :af ter  daemon'.’  In  some  eases  the  primary 
method  perforins  a  dearly-defined  action  and  the  choice  is  obvious:  :before  launch- rocket  puts 
in  die  fuel,  and  :after  .launch -rocket  turns  on  the  radar  tracking. 

In  other  eases  the  choice  can  be  less  obvious.  Consider  the  init  message,  winch  is  sent  to  a 
newly-created  object.  To  decide  what  kind  of  daemon  to  use,  we  observe  the  order  m  which 
daemon  methods  arc  called,  f  irst  the  :before  daemon  of  the  highest  level  of  absti action  is  called, 
then  :before  daemons  of  successively  lower  levels  of  abstraction  .uc  called,  and  finally  die  before 
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daemon  (if  any)  of  (he  base  flax  or  is  called.  Then  the  primary  method  is  called  Alter  that,  the 
:after  daemon  for  the  lowest  level  of  abstraction  is  called,  followed  by  the  after  daemons  at 
successively  higher  levels  of  abstraction. 

Now  it  there  is  no  interaction  among  all  these  methods,  if  tli  nr  actions  aie  completely 
orthogonal,  then  it  doesn't  matiei  whether  you  use  a  before  daemon  or  an  after  daemon.  It 
makes  a  dilleience  it'  there  is  some  interaction.  Ihe  interaction  we  aie  talking  about  is  usually 
done  through  instance  variables;  in  general,  instance  vat  tables  are  how  the  methods  of  different 
component  flavors  communicate  with  each  other.  In  the  case  of  the  and  message,  the  iwi-pliM 
can  be  used  as  well.  The  imp  irtant  thing  to  remember  is  that  no  uethod  knows  beforehand 
which  other  flavors  have  been  mixed  in  to  form  this  flavor,  a  method  cannot  make  any 
assumptions  about  how  this  llavr.r  has  been  combined,  and  in  what  order  the  various  components 
are  mixed. 

This  means  that  when  a  :before  daemon  has  run.  it  must  assume  that  none  of  the  methods 
for  this  message  have  run  yet.  But  the  :after  daemon  knows  that  the  Tefore  daemon  for  each  of 
the  other  flavors  has  run.  So  if  one  flavor  wants  to  convey  information  to  the  other,  flic  first  one 
should  "transmit"  the  information  in  a  :before  daemon,  and  the  second  one  should  "receive"  it  in 
an  :after  daemon.  So  while  the  :before  daemons  are  run.  information  is  "transmitted":  that  is, 
instance  variables  get  set  up.  I  hen,  when  the  :after  daemons  are  run.  they  can  look  at  the 
instance  variables  and  act  on  their  values. 

In  the  case  of  the  ;init  method,  the  (before  daemons  typically  set  up  instance  variables  of  the 
object  based  on  the  mit-plist.  while  the  :after  daemons  actually  do  things,  relying  on  the  fact  that 
all  of  the  instance  variables  have  been  initiah/cd  by  Lite  time  they  arc  called. 

Of  course,  since  flavors  arc  not  hierarchically  organized,  the  notion  of  levels  of  abstraction  is 
not  strictly  applicable.  However,  it  remains  a  useful  way  of  dunking  about  systems. 


1.13  Implementation  of  Flavors 

An  object  which  is  an  instance  of  a  flavor  is  implemented  using  the  data  type  dtp  instance. 
The  representation  is  a  structure  whose  first  word,  tagged  with  dtp- instance -header,  points  to  a 
structure  (known  to  the  microcode  as  an  "instance  descriptor")  containing  the  internal  data  for  the 
flavor,  and  whose  remaining  words  are  value  cells  containing  the  values  of  the  instance  variables. 
The  instance  descriptor  is  a  defstruct  which  appears  on  the  sidlavor  property  of  the  flavor  name. 
It  contains,  among  other  things,  the  name  of  the  flavor,  the  size  of  an  instance,  the  table  of 
methods  for  handling  messages,  and  information  for  accessing  the  instance  variables. 

defflavor  creates  such  a  data  structure  for  each  flavor,  and  links  them  together  according  to 
flic  dependency  relationships  between  flavors. 

A  message  is  sent  to  an  instance  simply  by  calling  it  as  a  function,  with  the  first  argument 
being  the  message  kcywoid.  flic  iniciocodc  binds  soil  to  the  object,  binds  the  instance  variables 
(as  special  closure  variables)  to  the  value  cells  in  the  instance,  and  calls  .1  dtp  select  mothod 
associated  with  the  flavor.  I  his  dtp  select  method  associates  the  message  keyword  to  the  actual 
function  to  be  called.  If  dicrc  is  only  one  method  this  is  th.it  method,  otherwise  it  is  an 
automatically-generated  function  which  calls  the  appropriate  methods  in  the  right  order.  If  there 
arc  wrappers,  they  arc  incorporated  into  this  automatically  generated  function. 
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The  function-specifier  syntax  (:method  flavor  name  Dpiional-meiliotl-iypc  message- name)  is 
understood  by  fdefine  and  related  functions.  It  is  preferable  to  refer  to  methods  this  way  rather 
than  by  explicit  use  of  the  flavor -method-symbol  (see  page  15). 


1.13.1  Order  of  Definition 

There  is  a  certain  amount  of  freedom  to  the  order  in  which  you  do  defflavor’s.  defmethod’s, 
and  defwrapper's.  This  freedom  is  designed  to  make  it  easy  to  load  programs  containing  complex 
flavor  structures  without  having  to  do  things  in  a  certain  order.  It  is  considered  important  that 
not  all  the  methods  for  a  flavor  need  be  defined  in  llic  same  file.  Thus  the  partitioning  of  a 
program  into  files  can  be  along  modular  lines. 

The  rules  for  the  order  of  definition  arc  as  follows. 

Before  a  method  can  be  defined  (with  defmethod  or  defwrapper)  its  flavor  must  have  been 
defined  (with  defflavor).  This  makes  sense  because  the  system  has  to  have  a  place  to  remember 
die  method,  and  because  it  has  to  know  the  instance- variables  of  the  flavor  if  die  method  is  to  be 
compiled. 

When  a  flavor  is  defined  (with  defflavor)  it  is  not  necessary  that  all  of  its  component  flavors 
be  defined  already.  This  is  to  allow  defflavor's  to  be  spread  between  files  according  to  the 
modularity  of  a  program,  and  to  provide  for  mutually-included  flavors  (see  the  included -flavors 
defflavor  option,  page  21).  Methods  can  be  defined  for  a  flavor  some  of  whose  component 
flavors  arc  not  yet  defined,  however  in  certain  eases  compiling  those  methods  will  produce  a 
spurious  warning  that  an  instance  variable  was  declared  special  (because  the  system  did  not  realize 
it  was  an  instance  variable).  In  die  current  implementation  these  warnings  may  be  ignored, 
although  diat  may  not  always  be  true  in  the  future. 

The  methods  automatically  generated  by  the  :gettable-  instance  -variables  and  :settable- 
instance- variables  defflavor  options  (see  page  20)  are  generated  at  the  time  the  defflavor  is 
done. 

Hie  first  time  a  flavor  is  instantiated,  die  system  looks  through  all  of  the  component  flavors 
and  gathers  various  information.  At  this  point  an  error  will  be  signalled  if  not  all  of  die 
components  have  been  defflavor'cd.  This  is  also  die  time  at  which  certain  other  errors  are 
detected,  for  instance  lack  of  a  required  instance-variable  (see  the  required- instance-variables 
defflavor  option,  page  21).  The  combined  methods  (see  page  12)  arc  generated  at  this  time  also, 
unless  they  already  exist.  Ihcy  will  already  exist  if  compile -flavor  methods  was  used,  but  if 
those  methods  are  obsolete  because  of  changes  made  to  component  flavors  since  the  compilation, 
new  combined  methods  will  be  made. 

Alter  a  flavor  lias  been  instantiated,  it  is  possible  to  make  changes  to  it.  These  changes  will 
affect  all  existing  instances  if  possible.  This  is  described  more  fully  immediately  below. 
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1.13.2  C  hanging  a  Flavor 

'»ou  tan  change  anything  ahout  a  flavor  at  any  tunc.  You  can  change  the  flavor's  general 
attributes  by  doing  another  defflavor  with  the  same  name.  You  can  add  or  modify  methods  by 
doing  defmethod’s.  It  you  do  a  defmethod  with  the  same  llavor-name.  message  name,  and 
(optional)  method-type  as  an  existing  method,  that  method  is  replaced  with  the  new  definition. 
Currently  there  is  no  good  way  to  remove  a  method. 

These  changes  will  always  oropagatc  to  all  flavors  that  depend  upon  the  changed  flavor 
Normally  the  system  will  propag.  te  the  changes  to  all  existing  instances  of  the  changed  flavor  and 
all  flavors  that  depend  on  it.  However,  this  is  not  possible  when  the  flavor  has  been  changed  so 
drastically  that  the  old  instances  would  not  work  properly  with  the  new  flavor  Ibis  happens  if 
you  change  the  number  of  instance  variables,  which  changes  the  si/c  of  an  instance.  It  also 
happens  if  you  change  the  ordtr  of  the  instance  variables  (and  hence  the  storage  layout  of  an 
instance),  or  if  you  change  the  component  flavors  (which  can  change  several  subtle  aspects  of  an 
instance).  The  system  docs  not  keep  a  list  of  all  die  instances  of  each  flavor,  so  it  cannot  find 
die  instances  and  modify  diem  to  conform  to  the  new  flavor  definition.  Instead  it  gives  you  a 
warning  message,  on  the  error -output  stream,  to  the  effect  that  the  flavor  was  changed 
incompatibly  and  the  old  instances  will  not  gel  the  new  version.  The  system  leaves  the  old  flavor 
data-struciurc  intact  (the  old  instances  will  continue  to  point  at  it)  and  makes  a  new  tine  to 
contain  the  new  version  of  the  flavor.  If  a  less  drastic  change  is  made,  the  system  modifies  the 
original  flavor  data-structurc.  duis  alfccting  the  old  instances  Uiat  point  at  it. 

One  exception  to  this  is  that  changes  to  defwrapper's  arc  never  automatically  propagated. 
This  is  because  doing  so  is  expensive  and  the  system  cannot  tell  whether  you  really  changed  it  or 
just  redefined  it  to  be  die  same  as  it  was.  (Note  dial  the  initial  definition  of  a  wrapper  is 
propagated,  but  redefinitions  of  it  arc  not.)  See  die  documentation  of  defwrapper  for  more 
details. 


1.13.3  Restrictions 

llierc  is  presently  an  implementation  restriction  that  when  using  daemons,  die  primary 
mcdiod  may  return  at  most  three  values  if  Uicre  arc  any  :after  daemons.  This  is  because  die 
combined  method  needs  a  place  to  remember  the  values  while  it  calls  the  daemons.  This  will  be 
fixed  some  day. 

In  this  implementation,  all  message  names  must  be  in  the  keyword  package,  in  order  for  the 
flavor-mcthod-symbols  (sec  page  15)  to  be  unique,  and  for  various  tools  in  die  editor  to  work 
correctly. 
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1.14  Entities 

An  entity  is  a  l  isp  object;  the  entity  is  one  of  the  primitive  dual  pcs  provided  by  the  l  isp 
Machine  system  (the  data  type  function  (sec  page  111  in  the  lisp  Machine  Manual)  will  return 
dtp-entity  if  it  is  given  an  entity).  Entities  arc  just  like  closures:  they  have  all  the  same 

attributes  and  functionality.  ITic  only  difference  between  the  two  primitive  types  is  their  data 

type:  entities  arc  clearly  distinguished  from  closures  because  they  have  a  different  data  type.  Ilic 
reason  there  is  an  important  difference  between  them  is  that  various  parts  of  the  (not  so  primitive) 
l.isp  system  treat  them  differently. 

A  closure  is  simply  a  kind  of  function,  but  an  entity  is  assumed  to  be  a  message- receiving 

object.  Thus,  when  the  l  isp  pi.ntcr  (sec  sections  18.2  and  18.4  in  the  I  isp  Machine  Manual)  is 

given  a  closure,  it  prints  a  simple  textual  representation,  but  when  it  is  handed  an  entity,  it  sends 
the  entity  a  print-self  message,  which  the  entity  is  expected  to  handle.  Ihc  describe  function 
(sec  page  261  in  the  l.isp  Machine  Manual)  also  sends  entities  messages  when  it  is  handed  them. 
So  when  you  want  to  make  a  message- receiving  object  out  of  a  closure,  as  described  on  page  7, 
you  should  use  an  entity  instead. 

Usually  there  is  no  point  in  using  entities  instead  of  flavors.  Entities  were  introduced  into 
l.isp  Machine  l.isp  before  flavors  were,  and  perhaps  they  would  not  have  been  had  flavors  already 
existed,  flavors  have  had  considerably  more  attention  paid  to  efficiency  and  to  good  tools  for 
using  them. 

(The  rest  of  this  section  is  not  yet  written.  It  would  explain  how  to  create  entities,  and  how 
the  defselect  function  is  used  to  make  a  function  that  dispatches  on  its  first  argument  at  relatively 
high  speed.] 

1.15  Useful  Editor  Commands 

Since  we  presently  lack  an  editor  manual,  this  section  briefly  documents  some  editor 
commands  that  are  useful  in  conjunction  with  flavors. 

meta-. 

The  meta-.  (Kdit  Definition)  command  can  find  the  definition  of  a  flavor  in  the  same 
way  that  it  can  find  the  definition  of  a  function. 

F.dit  I>finition  can  find  the  definition  of  a  method  if  you  give 
(  : method  flavor  type  message ) 

as  the  function  name.  'Ific  keyword  :method  may  be  omitted.  Completion  will  occur  on 
the  flavor  name  and  message  name  as  usual  with  l-dil  Definition. 

meta  X  Describe  Flavor 

Asks  for  a  flavor  name  in  the  mini-buffer  and  describes  its  characteristics.  When  typing 
the  flavor  name  you  have  completion  over  the  names  of  all  defined  flavors  (thus  this 
command  can  be  used  to  aid  in  guessing  the  name  of  a  flavor).  The  display  produced  is 
mouse  sensitive  where  there  arc  names  of  flavors  and  of  methods;  as  usual  the  right-hand 
mouse  button  gives  you  a  menu  of  operations  and  the  left-hand  mouse  button  docs  the 
most  common  operation,  typically  positioning  the  editor  to  the  source  code  for  the  thing 
you  arc  pointing  at. 
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meta-X  List  Methods 
meta-X  Edit  Methods 

Asks  you  for  a  message  in  the  mini-buffer  and  lists  all  the  flavors  which  have  a  method 
for  that  message.  You  may  type  in  the  message  name,  point  to  it  with  the  mouse,  or  let 
it  default  to  the  message  which  is  being  sent  by  the  l  isp  form  the  cursor  is  inside  of. 
List  Methods  produces  a  mouse-sensitive  display  allowing  you  to  edit  selected  methods  or 
just  see  which  flavors  have  methods,  while  Fid  it  Methods  skips  the  display  and  proceeds 
directly  to  editing  the  methods.  As  usual  with  this  type  of  command,  the  editor 
command  control-,  is  redefined  to  advance  the  editor  cursor  to  the  next  method  in  the 
list,  reading  in  its  source  file  if  necessary.  Typing  control -.  while  the  display  is  on  the 
screen  edits  the  first  method. 

meta-X  List  Combined  Methods 
meta-X  Edit  Combined  Methods 

Asks  you  for  a  message  and  a  flavor  in  two  mini-buffers  and  lists  all  the  methods  which 
would  be  called  if  that  message  were  sent  to  an  instance  of  that  flavor.  You  may  point  to 
the  message  and  flavor  with  the  mouse,  and  there  is  completion  for  the  flavor  name.  As 
in  List/F.dil  Methods,  the  display  is  mouse  sensitive  and  the  F'dil  version  of  the  command 
skips  die  display  and  proceeds  directly  to  the  editing  phase. 

l  ist  Combined  Methods  can  be  very  useful  for  telling  what  a  flavor  will  do  in  response  to 
a  message.  It  shows  you  the  primary  method,  the  daemons,  and  the  wrappers  and  lets 
you  sec  the  code  for  all  of  them;  type  control-,  to  get  to  successive  ones. 
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